loomiomcp 0.0.2 → 0.0.6

package/README.md

@@ -1,11 +1,17 @@
 # loomiomcp
 
+[![npm](https://img.shields.io/npm/v/loomiomcp)](https://www.npmjs.com/package/loomiomcp)
+[![CI](https://github.com/soil-dev/loomiomcp/actions/workflows/ci.yml/badge.svg)](https://github.com/soil-dev/loomiomcp/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Glama](https://glama.ai/mcp/servers/soil-dev/loomiomcp/badge)](https://glama.ai/mcp/servers/soil-dev/loomiomcp)
+
 Model Context Protocol server for [Loomio](https://www.loomio.com). Lets
 Claude (Desktop, Code, or web Projects via Custom Connector) read and
-write Loomio discussions, polls, comments, and group memberships in
-plain English. Targets Loomio's **b2** API — the canonical surface
-documented at [/help/api2](https://www.loomio.com/help/api2) and the
-namespace where the controllers actually live in the open-source repo.
+write Loomio discussions, polls, comments, and group memberships — and
+analyse member activity — in plain English. Targets Loomio's **b2** API
+— the canonical surface documented at
+[/help/api2](https://www.loomio.com/help/api2) and the namespace where
+the controllers actually live in the open-source repo.
 
 Tools (b2, per-user `?api_key=`):
 
@@ -16,11 +22,24 @@ Tools (b2, per-user `?api_key=`):
 - `list_polls(group_id, status?, limit?, offset?)` — list a group's polls
 - `create_poll(title, poll_type, …)` — start a new poll
 - `list_memberships(group_id, limit?, offset?)` — list a group's members with email
-  addresses (caller must be a group admin)
+  addresses. Requires the connector's user to be a group **admin** (coordinator);
+  Loomio only returns the member list to admins. On a 403 the connector probes to
+  explain *why* — bot lacks the admin role vs. invalid key vs. not-a-member — and
+  points at `get_user_activity` / `list_events` for names/ids (email stays admin-only).
 - `list_groups({start_id?, end_id?, stop_after_consecutive_misses?})` — enumerate
   visible groups by probing `b2/polls` across an id range. Loomio has no
   api-key-authed list-groups endpoint; this is the workaround. Default scans
   are ~50–200 outbound calls; a single invocation is capped at 500 ids
+- `list_events(discussion_id, limit?, offset?, kinds?)` — the event stream for one
+  discussion (comments, reactions, stances, outcomes, …) with `actor_id`, `kind`,
+  timestamps, and embedded `users` / `comments` / `polls`. With no `limit`/`offset`
+  it paginates up to a bounded cap and reports `scope.complete`; with either
+  pagination knob it returns that one page.
+- `get_user_activity(user_id, group_ids, since?, until?)` — aggregate one user's
+  participation across groups (counts by kind / group / month, first/last activity).
+  The primary tool for any user-centric question; fans out server-side with a bounded
+  budget and reports completeness via `scope.complete`. If both `since` and `until`
+  are supplied, `until` must be later than `since`.
 - `manage_memberships({group_id, emails, remove_absent})` — add and (with
   `remove_absent: true`) **remove** members. See SECURITY.md before using
   `remove_absent`.
@@ -58,10 +77,10 @@ Only relevant if you operate a Loomio instance.
 
 ## Read-only mode
 
-Set `LOOMIO_MCP_READONLY=1` to register only the read tools
-(`get_*` / `list_*`). All write tools (`create_*`, `manage_*`) are
-skipped at server-init time. This is the mode the Cloud Run deployment
-runs in.
+Set `LOOMIO_MCP_READONLY=1` to register only the 8 read tools
+(`get_*` / `list_*` / `get_user_activity`). All write tools
+(`create_*`, `manage_*`) are skipped at server-init time. This is the
+mode the Cloud Run deployment runs in.
 
 ## Docs map
 

package/dist/http.js

@@ -38,7 +38,7 @@ function logEvent(event, fields, opts = {}) {
 }
 function redactPath(path) {
   const noQuery = path.split("?")[0] ?? path;
-  return noQuery.replace(/\/\d+(?:,\d+)*/g, "/:id");
+  return noQuery.replace(/\/\d+(?:,\d+)*/g, "/:id").replace(/\/(discussions|polls)\/[^/]+/g, "/$1/:id");
 }
 var requestContext = new AsyncLocalStorage();
 function withRequestContext(initial, fn) {
@@ -187,8 +187,15 @@ async function fetchWithTimeout(url, options) {
 async function throwForStatus(res) {
   if (res.status === 401 || res.status === 403) {
     const detail = await parseErrorBody(res);
+    const detailStr = String(detail ?? "").trim();
+    let pathHint = "the requested resource";
+    try {
+      pathHint = redactPath(new URL(res.url).pathname);
+    } catch {
+    }
+    const detailSuffix = detailStr && detailStr !== String(res.status) ? `: ${detailStr}` : "";
     throw new LoomioAuthError(
-      `Loomio API returned ${res.status}: ${detail}. Check that LOOMIO_API_KEY is valid and has access to the requested resource.`,
+      `Loomio API returned ${res.status} for ${pathHint}${detailSuffix}. Loomio sends the same 403 whether the connector's key is invalid/expired OR the key's user simply lacks the role this resource requires (some endpoints \u2014 e.g. listing a group's members \u2014 require the group-admin/coordinator role). Verify the key, and that the bot user has the needed role on the target group.`,
       res.status
     );
   }
@@ -259,6 +266,21 @@ async function loomioGet(path, params) {
     start.cleanup();
   }
 }
+async function loomioGetStatus(path, params) {
+  const url = buildUrl(B2_AUTH, path, params);
+  const start = await doFetch(url, { headers: baseHeaders() });
+  try {
+    return await consumeBody(start, async () => {
+      try {
+        await start.res.text();
+      } catch {
+      }
+      return start.res.status;
+    });
+  } finally {
+    start.cleanup();
+  }
+}
 function encodeForm(body) {
   const u = new URLSearchParams();
   for (const [k, v] of Object.entries(body)) {
@@ -916,6 +938,9 @@ import { z as z2 } from "zod";
 var positiveId = z2.number().int().positive();
 var loomioKey = z2.string().regex(/^[A-Za-z0-9_-]+$/, "Loomio short keys may only contain letters, numbers, _ and -.");
 var idOrKey = z2.union([loomioKey, positiveId]);
+var isoTimestamp = z2.string().refine((v) => !Number.isNaN(Date.parse(v)), {
+  message: "must be a parseable ISO-8601 timestamp (e.g. 2026-01-31 or 2026-01-31T00:00:00Z)."
+}).optional();
 function encodePathSegment(value) {
   const raw = String(value);
   if (raw === "" || raw === "." || raw === "..") {
@@ -1060,19 +1085,75 @@ async function createPoll(input) {
 
 // src/tools/memberships.ts
 import { z as z5 } from "zod";
+
+// src/loomio/access.ts
+async function classifyGroupForbidden(groupId) {
+  const probeStatus = await loomioGetStatus("/b2/polls", {
+    group_id: groupId,
+    limit: 1,
+    status: "all"
+  });
+  if (probeStatus === 200) return { kind: "not_admin" };
+  if (probeStatus === 403) return { kind: "no_access" };
+  return { kind: "inconclusive", probeStatus };
+}
+function adminRequiredError(opts) {
+  const { groupId, resource, classification, fallback } = opts;
+  const tail = fallback ? ` ${fallback}` : "";
+  switch (classification.kind) {
+    case "not_admin":
+      return new LoomioAuthError(
+        `Loomio denied access to ${resource} for group ${groupId} (HTTP 403). The connector's Loomio key is valid \u2014 it can read group ${groupId} \u2014 but this data is only visible to a group admin (coordinator), and the connector's bot user is a plain member. This is a Loomio permission boundary, not a connector or client bug, and it is often intentional: the bot is deliberately kept as a non-admin so it can't read everyone's email. If this data is genuinely needed, a coordinator of group ${groupId} can grant the bot the coordinator role (Loomio \u2192 the group \u2192 Members \u2192 the bot user \u2192 Make coordinator).${tail}`,
+        403
+      );
+    case "no_access":
+      return new LoomioAuthError(
+        `Loomio denied access to ${resource} for group ${groupId} (HTTP 403), and a follow-up check shows the connector can't read group ${groupId} at all. That means one of: the Loomio API key is invalid or expired, or the connector's bot user is not a member of group ${groupId}. Verify LOOMIO_API_KEY and that the bot has been added to the group.`,
+        403
+      );
+    default:
+      return new LoomioAuthError(
+        `Loomio denied access to ${resource} for group ${groupId} (HTTP 403). This endpoint typically requires the connector's bot user to be an admin (coordinator) of the group, but a follow-up access check was inconclusive (HTTP ${classification.probeStatus}), so the exact cause \u2014 missing admin role, an invalid key, or the bot not being a member \u2014 couldn't be confirmed. Verify the group id, the API key, and the bot's role on the group.${tail}`,
+        403
+      );
+  }
+}
+
+// src/tools/memberships.ts
+var NON_ADMIN_FALLBACK = "Member display names, usernames, and ids (but not email addresses) are available without admin via get_user_activity / list_events, which read the group's event stream.";
+async function explainForbidden(groupId, original, resource, fallback) {
+  try {
+    const classification = await classifyGroupForbidden(groupId);
+    return adminRequiredError({ groupId, resource, classification, fallback });
+  } catch {
+    return original;
+  }
+}
 var listMembershipsSchema = z5.object({
   group_id: positiveId.describe(
-    "ID of the Loomio group whose memberships to list (required). Caller must be a group admin; the response includes member email addresses."
+    "ID of the Loomio group whose memberships to list (required). The connector's bot user must be an admin (coordinator) of the group \u2014 Loomio only returns the member list, including email addresses, to group admins. For a non-admin bot this returns a clear 403 explaining the role requirement; names/usernames/ids (not emails) are still reachable via get_user_activity / list_events."
   ),
   limit: z5.number().int().min(1).max(200).optional().describe("Page size. Loomio defaults to 50."),
   offset: z5.number().int().min(0).optional().describe("Page offset. Defaults to 0.")
 });
 async function listMemberships(input) {
-  return loomioGet("/b2/memberships", {
-    group_id: input.group_id,
-    ...input.limit !== void 0 ? { limit: input.limit } : {},
-    ...input.offset !== void 0 ? { offset: input.offset } : {}
-  });
+  try {
+    return await loomioGet("/b2/memberships", {
+      group_id: input.group_id,
+      ...input.limit !== void 0 ? { limit: input.limit } : {},
+      ...input.offset !== void 0 ? { offset: input.offset } : {}
+    });
+  } catch (err) {
+    if (err instanceof LoomioAuthError && err.status === 403) {
+      throw await explainForbidden(
+        input.group_id,
+        err,
+        "the member list (names, emails, roles)",
+        NON_ADMIN_FALLBACK
+      );
+    }
+    throw err;
+  }
 }
 var manageMembershipsSchema = z5.object({
   group_id: positiveId.describe(
@@ -1086,7 +1167,14 @@ var manageMembershipsSchema = z5.object({
   )
 });
 async function manageMemberships(input) {
-  return loomioPost("/b2/memberships", input);
+  try {
+    return await loomioPost("/b2/memberships", input);
+  } catch (err) {
+    if (err instanceof LoomioAuthError && err.status === 403) {
+      throw await explainForbidden(input.group_id, err, "membership changes");
+    }
+    throw err;
+  }
 }
 
 // src/tools/groups.ts
@@ -1197,34 +1285,79 @@ async function listGroups(input) {
 
 // src/tools/events.ts
 import { z as z7 } from "zod";
+var CONCURRENCY2 = 6;
+var EVENTS_PAGE_SIZE = 200;
+var MAX_EVENTS_PAGES = 10;
+var MAX_DISCUSSION_PAGES = 20;
+var MAX_SCAN_DISCUSSIONS = 500;
 var listEventsSchema = z7.object({
   discussion_id: positiveId.describe(
     "ID of the discussion whose event stream to fetch. Required \u2014 Loomio's v1/events endpoint silently returns empty without it."
   ),
-  limit: z7.number().int().min(1).max(200).optional().describe("Page size. Loomio defaults to 50; cap is 200."),
-  offset: z7.number().int().min(0).optional().describe("Page offset (Loomio's `from` parameter). Defaults to 0."),
+  limit: z7.number().int().min(1).max(200).optional().describe(
+    "Page size for a single-page fetch. Omit limit/offset to let the connector paginate the full discussion stream up to its bounded cap."
+  ),
+  offset: z7.number().int().min(0).optional().describe(
+    "Page offset (Loomio's `from` parameter). When supplied, list_events returns exactly that page instead of auto-paginating."
+  ),
   kinds: z7.array(z7.string().min(1)).optional().describe(
     "Optional filter to only these event kinds (applied client-side after fetch \u2014 Loomio doesn't filter `kind` server-side). Common kinds: new_discussion, new_comment, comment_edited, poll_created, stance_created, outcome_created, discussion_moved, discussion_closed, reaction."
   )
 });
+function mergeEventResponse(into, from) {
+  into.events = [...into.events ?? [], ...from.events ?? []];
+  into.comments = [...into.comments ?? [], ...from.comments ?? []];
+  into.users = [...into.users ?? [], ...from.users ?? []];
+  into.polls = [...into.polls ?? [], ...from.polls ?? []];
+  into.parent_events = [...into.parent_events ?? [], ...from.parent_events ?? []];
+  into.meta = from.meta ?? into.meta;
+}
+function filterKinds(resp, kinds) {
+  if (!kinds?.length) return resp;
+  const allowed = new Set(kinds);
+  return {
+    ...resp,
+    events: (resp.events ?? []).filter((e) => allowed.has(e.kind))
+  };
+}
 async function listEvents(input) {
-  const resp = await loomioGet("/v1/events", {
-    discussion_id: input.discussion_id,
-    ...input.limit !== void 0 ? { per: input.limit } : {},
-    ...input.offset !== void 0 ? { from: input.offset } : {}
-  });
-  if (input.kinds?.length) {
-    const allowed = new Set(input.kinds);
-    return {
-      ...resp,
-      events: (resp.events ?? []).filter((e) => allowed.has(e.kind))
-    };
+  if (input.limit !== void 0 || input.offset !== void 0) {
+    const resp = await loomioGet("/v1/events", {
+      discussion_id: input.discussion_id,
+      ...input.limit !== void 0 ? { per: input.limit } : {},
+      ...input.offset !== void 0 ? { from: input.offset } : {}
+    });
+    return filterKinds(resp, input.kinds);
   }
-  return resp;
+  const merged = {};
+  let offset = 0;
+  let pagesFetched = 0;
+  let truncated = false;
+  for (let page = 0; page < MAX_EVENTS_PAGES; page++) {
+    const resp = await loomioGet("/v1/events", {
+      discussion_id: input.discussion_id,
+      per: EVENTS_PAGE_SIZE,
+      from: offset
+    });
+    pagesFetched++;
+    const evs = resp.events ?? [];
+    mergeEventResponse(merged, resp);
+    if (evs.length < EVENTS_PAGE_SIZE) break;
+    offset += EVENTS_PAGE_SIZE;
+    if (page === MAX_EVENTS_PAGES - 1) truncated = true;
+  }
+  return filterKinds(
+    {
+      ...merged,
+      scope: {
+        complete: !truncated,
+        pages_fetched: pagesFetched,
+        events_truncated: truncated
+      }
+    },
+    input.kinds
+  );
 }
-var CONCURRENCY2 = 6;
-var EVENTS_PAGE_SIZE = 200;
-var MAX_EVENTS_PAGES = 10;
 var ACTIVITY_KINDS = /* @__PURE__ */ new Set([
   "new_discussion",
   "new_comment",
@@ -1240,13 +1373,27 @@ var getUserActivitySchema = z7.object({
   group_ids: z7.array(positiveId).min(1).max(50).describe(
     "Groups to scan. Required \u2014 pass the result of `list_groups` (or a subset of it) to make the cost explicit. ~1 outbound HTTP request per discussion in scope, plus one list_discussions call per group; ~100-300 calls is typical for a wide scan. Capped at 50 groups per call."
   ),
-  since: z7.string().optional().describe("ISO-8601 timestamp; ignore events before this time."),
-  until: z7.string().optional().describe("ISO-8601 timestamp; ignore events at or after this time.")
+  since: isoTimestamp.describe(
+    "ISO-8601 timestamp; ignore events before this time. Rejected if unparseable (so a typo can't silently widen the scan to all history)."
+  ),
+  until: isoTimestamp.describe(
+    "ISO-8601 timestamp; ignore events at or after this time. Rejected if unparseable."
+  )
+}).superRefine((input, ctx) => {
+  if (!input.since || !input.until) return;
+  if (Date.parse(input.until) <= Date.parse(input.since)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["until"],
+      message: "until must be later than since."
+    });
+  }
 });
 async function listDiscussionIdsForGroup(groupId) {
   const all = [];
   let offset = 0;
-  for (let page = 0; page < 20; page++) {
+  let truncated = false;
+  for (let page = 0; page < MAX_DISCUSSION_PAGES; page++) {
     const resp = await loomioGet("/b2/discussions", {
       group_id: groupId,
       status: "all",
@@ -1257,12 +1404,14 @@ async function listDiscussionIdsForGroup(groupId) {
     for (const d of ds) all.push({ id: d.id, group_id: groupId });
     if (ds.length < EVENTS_PAGE_SIZE) break;
     offset += EVENTS_PAGE_SIZE;
+    if (page === MAX_DISCUSSION_PAGES - 1) truncated = true;
   }
-  return all;
+  return { discussions: all, truncated };
 }
 async function fetchAllEventsForDiscussion(discussionId) {
   const all = [];
   let offset = 0;
+  let truncated = false;
   for (let page = 0; page < MAX_EVENTS_PAGES; page++) {
     const resp = await loomioGet("/v1/events", {
       discussion_id: discussionId,
@@ -1273,10 +1422,11 @@ async function fetchAllEventsForDiscussion(discussionId) {
     for (const e of evs) all.push(e);
     if (evs.length < EVENTS_PAGE_SIZE) break;
     offset += EVENTS_PAGE_SIZE;
+    if (page === MAX_EVENTS_PAGES - 1) truncated = true;
   }
-  return all;
+  return { events: all, truncated };
 }
-async function runWithConcurrency(items, worker, concurrency) {
+async function runWithConcurrency(items, worker, concurrency, recoverError = () => true) {
   const results = new Array(items.length).fill(null);
   let next = 0;
   async function take() {
@@ -1285,7 +1435,8 @@ async function runWithConcurrency(items, worker, concurrency) {
       if (i >= items.length) return;
       try {
         results[i] = await worker(items[i]);
-      } catch {
+      } catch (err) {
+        if (!recoverError(err)) throw err;
         results[i] = null;
       }
     }
@@ -1293,26 +1444,55 @@ async function runWithConcurrency(items, worker, concurrency) {
   await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, take));
   return results;
 }
+function isRecoverableScanError(err) {
+  if (err instanceof LoomioAuthError) return err.status === 403;
+  return err instanceof LoomioApiError;
+}
+function rememberRecentSample(samples, e) {
+  samples.push({
+    kind: e.kind,
+    discussion_id: e.discussion_id,
+    created_at: e.created_at,
+    eventable_type: e.eventable_type,
+    eventable_id: e.eventable_id
+  });
+  samples.sort((a, b) => Date.parse(b.created_at) - Date.parse(a.created_at));
+  if (samples.length > 10) samples.length = 10;
+}
 async function getUserActivity(input) {
   const groupIds = [...new Set(input.group_ids)];
   const groupDiscussionLists = await runWithConcurrency(
     groupIds,
     (gid) => listDiscussionIdsForGroup(gid),
-    CONCURRENCY2
+    CONCURRENCY2,
+    isRecoverableScanError
   );
+  const groupsFailed = [];
+  const groupsTruncated = [];
   const discussions = [];
-  for (const list of groupDiscussionLists) {
-    if (list) discussions.push(...list);
-  }
+  groupDiscussionLists.forEach((list, i) => {
+    if (list) {
+      discussions.push(...list.discussions);
+      if (list.truncated) groupsTruncated.push(groupIds[i]);
+    } else {
+      groupsFailed.push(groupIds[i]);
+    }
+  });
+  const discussionsCapped = discussions.length > MAX_SCAN_DISCUSSIONS;
+  const scanDiscussions = discussionsCapped ? discussions.slice(0, MAX_SCAN_DISCUSSIONS) : discussions;
   const since = input.since ? Date.parse(input.since) : Number.NEGATIVE_INFINITY;
   const until = input.until ? Date.parse(input.until) : Number.POSITIVE_INFINITY;
   let eventsExamined = 0;
+  let discussionsFailed = 0;
+  let discussionsTruncated = 0;
   const counts = {
     total: 0,
     new_discussion: 0,
     new_comment: 0,
+    comment_edited: 0,
     poll_created: 0,
     stance_created: 0,
+    stance_updated: 0,
     outcome_created: 0,
     reaction: 0,
     other: 0
@@ -1323,12 +1503,20 @@ async function getUserActivity(input) {
   let lastActivity = null;
   const samples = [];
   const eventStreams = await runWithConcurrency(
-    discussions,
-    async (d) => ({ groupId: d.group_id, events: await fetchAllEventsForDiscussion(d.id) }),
-    CONCURRENCY2
+    scanDiscussions,
+    async (d) => {
+      const { events, truncated } = await fetchAllEventsForDiscussion(d.id);
+      return { groupId: d.group_id, events, truncated };
+    },
+    CONCURRENCY2,
+    isRecoverableScanError
   );
   for (const s of eventStreams) {
-    if (!s) continue;
+    if (!s) {
+      discussionsFailed++;
+      continue;
+    }
+    if (s.truncated) discussionsTruncated++;
     for (const e of s.events) {
       eventsExamined++;
       if (e.actor_id !== input.user_id) continue;
@@ -1346,25 +1534,24 @@ async function getUserActivity(input) {
       byMonth[month] = (byMonth[month] ?? 0) + 1;
       if (!firstActivity || e.created_at < firstActivity) firstActivity = e.created_at;
       if (!lastActivity || e.created_at > lastActivity) lastActivity = e.created_at;
-      if (samples.length < 10) {
-        samples.push({
-          kind: e.kind,
-          discussion_id: e.discussion_id,
-          created_at: e.created_at,
-          eventable_type: e.eventable_type,
-          eventable_id: e.eventable_id
-        });
-      }
+      rememberRecentSample(samples, e);
     }
   }
+  const complete = groupsFailed.length === 0 && discussionsFailed === 0 && discussionsTruncated === 0 && groupsTruncated.length === 0 && !discussionsCapped;
   return {
     user_id: input.user_id,
     scope: {
       group_ids: groupIds,
-      discussions_scanned: discussions.length,
+      discussions_scanned: scanDiscussions.length,
       events_examined: eventsExamined,
       since: input.since ?? null,
-      until: input.until ?? null
+      until: input.until ?? null,
+      complete,
+      groups_failed: groupsFailed,
+      discussions_failed: discussionsFailed,
+      discussions_truncated: discussionsTruncated,
+      discussions_capped: discussionsCapped,
+      groups_truncated: groupsTruncated
     },
     counts,
     by_group: byGroup,
@@ -1413,8 +1600,9 @@ function createLoomioMcpServer() {
   const b3Enabled = hasB3ApiKey();
   const server = new McpServer({
     name: "loomiomcp",
-    version: "0.1.0",
-    description: "MCP server for Loomio (loomio.com / self-hosted). Wraps Loomio's b2 public API: read and create discussions, polls, comments, plus list and manage group memberships. Read-only mode supported via LOOMIO_MCP_READONLY=1 (Cloud Run pattern). Optional b3 admin operations (deactivate / reactivate user) when LOOMIO_B3_API_KEY is set \u2014 instance operators only. Read tools annotated with readOnlyHint so MCP clients can auto-approve safe calls; destructive writes (manage_memberships with remove_absent, deactivate_user) carry destructiveHint.",
+    // Keep in sync with package.json on each release.
+    version: "0.0.6",
+    description: "MCP server for Loomio (loomio.com / self-hosted). Wraps Loomio's b2 public API: read and create discussions, polls, and comments; list and manage group memberships; read per-discussion event streams; and aggregate a user's participation across groups. Read-only mode supported via LOOMIO_MCP_READONLY=1 (Cloud Run pattern). Optional b3 admin operations (deactivate / reactivate user) when LOOMIO_B3_API_KEY is set \u2014 instance operators only. Read tools annotated with readOnlyHint so MCP clients can auto-approve safe calls; destructive writes (manage_memberships with remove_absent, deactivate_user) carry destructiveHint.",
     websiteUrl: "https://github.com/soil-dev/loomiomcp",
     icons: ICONS
   });
@@ -1451,7 +1639,7 @@ function createLoomioMcpServer() {
   registerTool(
     server,
     "list_polls",
-    "List polls in a Loomio group, ordered by creation date (newest first). Required: `group_id`. Optional `status` filter \u2014 'active' (default), 'closed', 'all' (every kept poll); `limit` 1-200 (default 50); `offset` for pagination. Caller must be a group member. Use to answer 'what's up for vote in group X', 'show me past poll results', or before create_poll to check what's already proposed.",
+    "List polls in a Loomio group, ordered by creation date (newest first). Required: `group_id`. Optional `status` filter \u2014 'active' (default), 'closed', 'all' (every kept poll); `limit` 1-200 (default 50); `offset` for pagination. Caller must be a group member. Use to answer 'what's up for vote in group X', 'show me past poll results', or before create_poll to check what's already proposed. FOR PER-USER PARTICIPATION QUESTIONS \u2014 'who voted', 'how often did X vote', 'compare members' turnout' \u2014 prefer `get_user_activity`. It returns participation directly (via the underlying events stream) and avoids the ambiguity between 'didn't vote' and 'abstained' that you can't tell apart from a `list_polls` response alone.",
     listPollsSchema,
     listPolls
   );
@@ -1467,7 +1655,7 @@ function createLoomioMcpServer() {
   registerTool(
     server,
     "list_memberships",
-    "List members of a Loomio group with their email addresses, roles, and join state. Required: `group_id`. Caller MUST be a group admin (non-admins get HTTP 403; the response is server-side scoped to include `include_email: true`). Optional `limit` 1-200 (default 50) and `offset` for pagination. Use to answer 'who's in group X', 'find a member by email', or \u2014 critically \u2014 BEFORE calling manage_memberships with remove_absent=true, since the diff between current and intended members is what makes that destructive call safe.",
+    "List members of a Loomio group with their email addresses, roles, and join state. Required: `group_id`. Caller MUST be a group admin (non-admins get HTTP 403; the response is server-side scoped to include `include_email: true`). Optional `limit` 1-200 (default 50) and `offset` for pagination. Use to answer 'who's in group X', 'find a member by email', or \u2014 critically \u2014 BEFORE calling manage_memberships with remove_absent=true, since the diff between current and intended members is what makes that destructive call safe. Do NOT use this tool to construct a participation analysis (e.g. 'how active is each member', 'who voted in our polls') by combining its output with `list_polls`. That reconstruction is more expensive in round-trips AND ambiguous about abstain-vs-didn't-vote. Use `get_user_activity` per member instead \u2014 it answers participation directly from the event stream.",
     listMembershipsSchema,
     listMemberships
   );
@@ -1481,14 +1669,14 @@ function createLoomioMcpServer() {
   registerTool(
     server,
     "list_events",
-    "Fetch the full event stream for one discussion \u2014 every new_comment, poll_created, stance_created, outcome_created, reaction, discussion_moved, etc. \u2014 with actor_id, kind, parent_id, created_at, and pointers to the underlying eventable record. Required: `discussion_id`. Optional `limit` (1-200, default 50), `offset` (Loomio's `from` param), and `kinds` (client-side filter to specific event kinds). The response also embeds related `comments`, `users`, and `polls` arrays for in-place resolution. Use this to answer 'show me the reply tree for thread X', 'who participated in discussion Y', or as the building block for cross-discussion aggregations. Loomio's v1/events endpoint requires a discussion_id; there's no instance-wide or per-user index \u2014 for user-centric questions, use `get_user_activity`.",
+    "Fetch the event stream for ONE discussion \u2014 new_comment, poll_created, stance_created, outcome_created, reaction, discussion_moved, etc. \u2014 with actor_id, kind, parent_id, created_at, and pointers to the underlying eventable record. Required: `discussion_id`. By default the connector paginates Loomio's v1/events endpoint up to a bounded cap and returns `scope.complete`; if you pass `limit` and/or `offset`, it returns exactly that one page. Optional `kinds` filters client-side after fetch. The response also embeds related `comments`, `users`, and `polls` arrays for in-place resolution. Use this to answer 'show me the reply tree for thread X', 'who participated in discussion Y', or as the building block for cross-discussion aggregations. Loomio's v1/events endpoint REQUIRES a discussion_id; there is no instance-wide, per-group, or per-user index. For user-centric questions across many discussions ('how active is X', 'compare members across groups'), use `get_user_activity` \u2014 do NOT loop `list_events` over every discussion yourself. `get_user_activity` does that fan-out server-side with concurrency control.",
     listEventsSchema,
     listEvents
   );
   registerTool(
     server,
     "get_user_activity",
-    "Aggregate one user's activity across a set of groups. Server-side: fans out across every discussion in the specified groups, fetches its event stream, filters to events authored by the target user, and returns counts (by kind, by group, by month), plus first/last activity timestamps and a sample of recent events. Required: `user_id`, `group_ids` (1-50; pass the result of `list_groups` for instance-wide). Optional `since` / `until` (ISO-8601) bound the time window. Cost: one outbound HTTP call per discussion in scope (plus one `list_discussions` per group). Wide scans of an active instance commonly hit 100-300 calls in 5-30 seconds. Concurrency-capped at 6. Use this for 'tell me about user X', 'how active has user Y been in Q1', or before promoting/awarding someone. For one discussion at a time, use `list_events`.",
+    "Aggregate one user's activity across a set of groups. Server-side: fans out across every discussion in the specified groups, fetches its event stream, filters to events authored by the target user, and returns counts (by kind, by group, by month), plus first/last activity timestamps and a sample of recent events. Required: `user_id`, `group_ids` (1-50; pass the result of `list_groups` for instance-wide). Optional `since` / `until` (ISO-8601) bound the time window; `until` must be later than `since` when both are supplied. USE THIS for any user-centric question \u2014 single-user OR comparing multiple users. Examples that all map to this tool: 'tell me about user X', 'how active has Y been in Q1', 'compare participation across two groups (e.g. two teams or committees)', 'rank members of group N by participation', 'who's the most engaged contributor since June', 'build a participation card for each member'. For an N-user comparison, **call this tool N times** (once per user) \u2014 that's the intended pattern and is materially cheaper than reconstructing the same data from `list_polls` + `list_memberships`. Why call this instead of fanning out `list_polls`/`list_memberships` yourself: (1) Participation here is read from the canonical event stream \u2014 'voted' vs 'didn't vote' is unambiguous; you can't tell those apart from `list_polls` alone. (2) Round-trip count is the same or lower in aggregate, because each user's activity scan reuses the same `list_discussions` fetches in your conversation context. (3) The result is pre-aggregated by kind/group/month \u2014 Claude doesn't need to count anything client-side. Cost: one outbound HTTP call per discussion in scope (plus one `list_discussions` per group). A single user-activity call on a ~200-discussion instance is ~200 calls in 5-10 seconds, concurrency-capped at 6. That sounds large but is the correct denominator for comparison: building the same answer from `list_polls` requires the same discussion-scan + a separate `list_memberships` per group + client-side cross-referencing. The fan-out is bounded by a global cap, so a single call can't run away. COMPLETENESS: check `scope.complete`. When it's false the counts are a LOWER BOUND \u2014 inspect `scope.groups_failed` (groups the bot couldn't read, e.g. it isn't a member), `scope.groups_truncated` (a group's discussion listing hit the page cap), `scope.discussions_failed`, `scope.discussions_truncated` (very long threads), and `scope.discussions_capped` (scan hit the global ceiling). Report partial results as partial; don't present them as the whole picture. For one discussion at a time, use `list_events`. For 'what groups can the user see', use `list_groups` first to scope the call.",
     getUserActivitySchema,
     getUserActivity
   );
@@ -1584,11 +1772,18 @@ function mountTransport(app2, opts) {
     limit: rateLimitMax,
     standardHeaders: "draft-7",
     legacyHeaders: false,
-    keyGenerator: (req) => {
-      const clientId = req.auth?.clientId;
-      if (clientId) return clientId;
-      return ipKeyGenerator(req.ip ?? "");
-    },
+    // Key the limiter on the SOURCE IP, never the OAuth client_id.
+    // Under open DCR (the public deployment) any caller can POST
+    // /register for unlimited fresh client_ids, so keying on client_id
+    // would let one source mint a brand-new 300/min bucket at will —
+    // silently defeating the limit. trust proxy=1 (Cloud Run's single
+    // front-end hop) makes req.ip the real client address (not
+    // X-Forwarded-For-spoofable past that hop), and ipKeyGenerator
+    // normalises IPv6 to a /56 so a /128 walk can't sidestep it. In
+    // static-client mode this is also strictly better than the old
+    // behaviour, which bucketed every caller under the one shared
+    // client_id.
+    keyGenerator: (req) => ipKeyGenerator(req.ip ?? ""),
     skip: () => rateLimitDisabled,
     handler: (_req, res) => {
       res.status(429).json({

package/dist/index.js

@@ -36,7 +36,7 @@ function logEvent(event, fields, opts = {}) {
 }
 function redactPath(path) {
   const noQuery = path.split("?")[0] ?? path;
-  return noQuery.replace(/\/\d+(?:,\d+)*/g, "/:id");
+  return noQuery.replace(/\/\d+(?:,\d+)*/g, "/:id").replace(/\/(discussions|polls)\/[^/]+/g, "/$1/:id");
 }
 var requestContext = new AsyncLocalStorage();
 function getRequestContext() {
@@ -164,8 +164,15 @@ async function fetchWithTimeout(url, options) {
 async function throwForStatus(res) {
   if (res.status === 401 || res.status === 403) {
     const detail = await parseErrorBody(res);
+    const detailStr = String(detail ?? "").trim();
+    let pathHint = "the requested resource";
+    try {
+      pathHint = redactPath(new URL(res.url).pathname);
+    } catch {
+    }
+    const detailSuffix = detailStr && detailStr !== String(res.status) ? `: ${detailStr}` : "";
     throw new LoomioAuthError(
-      `Loomio API returned ${res.status}: ${detail}. Check that LOOMIO_API_KEY is valid and has access to the requested resource.`,
+      `Loomio API returned ${res.status} for ${pathHint}${detailSuffix}. Loomio sends the same 403 whether the connector's key is invalid/expired OR the key's user simply lacks the role this resource requires (some endpoints \u2014 e.g. listing a group's members \u2014 require the group-admin/coordinator role). Verify the key, and that the bot user has the needed role on the target group.`,
       res.status
     );
   }
@@ -236,6 +243,21 @@ async function loomioGet(path, params) {
     start.cleanup();
   }
 }
+async function loomioGetStatus(path, params) {
+  const url = buildUrl(B2_AUTH, path, params);
+  const start = await doFetch(url, { headers: baseHeaders() });
+  try {
+    return await consumeBody(start, async () => {
+      try {
+        await start.res.text();
+      } catch {
+      }
+      return start.res.status;
+    });
+  } finally {
+    start.cleanup();
+  }
+}
 function encodeForm(body) {
   const u = new URLSearchParams();
   for (const [k, v] of Object.entries(body)) {
@@ -364,6 +386,9 @@ import { z } from "zod";
 var positiveId = z.number().int().positive();
 var loomioKey = z.string().regex(/^[A-Za-z0-9_-]+$/, "Loomio short keys may only contain letters, numbers, _ and -.");
 var idOrKey = z.union([loomioKey, positiveId]);
+var isoTimestamp = z.string().refine((v) => !Number.isNaN(Date.parse(v)), {
+  message: "must be a parseable ISO-8601 timestamp (e.g. 2026-01-31 or 2026-01-31T00:00:00Z)."
+}).optional();
 function encodePathSegment(value) {
   const raw = String(value);
   if (raw === "" || raw === "." || raw === "..") {
@@ -508,19 +533,75 @@ async function createPoll(input) {
 
 // src/tools/memberships.ts
 import { z as z4 } from "zod";
+
+// src/loomio/access.ts
+async function classifyGroupForbidden(groupId) {
+  const probeStatus = await loomioGetStatus("/b2/polls", {
+    group_id: groupId,
+    limit: 1,
+    status: "all"
+  });
+  if (probeStatus === 200) return { kind: "not_admin" };
+  if (probeStatus === 403) return { kind: "no_access" };
+  return { kind: "inconclusive", probeStatus };
+}
+function adminRequiredError(opts) {
+  const { groupId, resource, classification, fallback } = opts;
+  const tail = fallback ? ` ${fallback}` : "";
+  switch (classification.kind) {
+    case "not_admin":
+      return new LoomioAuthError(
+        `Loomio denied access to ${resource} for group ${groupId} (HTTP 403). The connector's Loomio key is valid \u2014 it can read group ${groupId} \u2014 but this data is only visible to a group admin (coordinator), and the connector's bot user is a plain member. This is a Loomio permission boundary, not a connector or client bug, and it is often intentional: the bot is deliberately kept as a non-admin so it can't read everyone's email. If this data is genuinely needed, a coordinator of group ${groupId} can grant the bot the coordinator role (Loomio \u2192 the group \u2192 Members \u2192 the bot user \u2192 Make coordinator).${tail}`,
+        403
+      );
+    case "no_access":
+      return new LoomioAuthError(
+        `Loomio denied access to ${resource} for group ${groupId} (HTTP 403), and a follow-up check shows the connector can't read group ${groupId} at all. That means one of: the Loomio API key is invalid or expired, or the connector's bot user is not a member of group ${groupId}. Verify LOOMIO_API_KEY and that the bot has been added to the group.`,
+        403
+      );
+    default:
+      return new LoomioAuthError(
+        `Loomio denied access to ${resource} for group ${groupId} (HTTP 403). This endpoint typically requires the connector's bot user to be an admin (coordinator) of the group, but a follow-up access check was inconclusive (HTTP ${classification.probeStatus}), so the exact cause \u2014 missing admin role, an invalid key, or the bot not being a member \u2014 couldn't be confirmed. Verify the group id, the API key, and the bot's role on the group.${tail}`,
+        403
+      );
+  }
+}
+
+// src/tools/memberships.ts
+var NON_ADMIN_FALLBACK = "Member display names, usernames, and ids (but not email addresses) are available without admin via get_user_activity / list_events, which read the group's event stream.";
+async function explainForbidden(groupId, original, resource, fallback) {
+  try {
+    const classification = await classifyGroupForbidden(groupId);
+    return adminRequiredError({ groupId, resource, classification, fallback });
+  } catch {
+    return original;
+  }
+}
 var listMembershipsSchema = z4.object({
   group_id: positiveId.describe(
-    "ID of the Loomio group whose memberships to list (required). Caller must be a group admin; the response includes member email addresses."
+    "ID of the Loomio group whose memberships to list (required). The connector's bot user must be an admin (coordinator) of the group \u2014 Loomio only returns the member list, including email addresses, to group admins. For a non-admin bot this returns a clear 403 explaining the role requirement; names/usernames/ids (not emails) are still reachable via get_user_activity / list_events."
   ),
   limit: z4.number().int().min(1).max(200).optional().describe("Page size. Loomio defaults to 50."),
   offset: z4.number().int().min(0).optional().describe("Page offset. Defaults to 0.")
 });
 async function listMemberships(input) {
-  return loomioGet("/b2/memberships", {
-    group_id: input.group_id,
-    ...input.limit !== void 0 ? { limit: input.limit } : {},
-    ...input.offset !== void 0 ? { offset: input.offset } : {}
-  });
+  try {
+    return await loomioGet("/b2/memberships", {
+      group_id: input.group_id,
+      ...input.limit !== void 0 ? { limit: input.limit } : {},
+      ...input.offset !== void 0 ? { offset: input.offset } : {}
+    });
+  } catch (err) {
+    if (err instanceof LoomioAuthError && err.status === 403) {
+      throw await explainForbidden(
+        input.group_id,
+        err,
+        "the member list (names, emails, roles)",
+        NON_ADMIN_FALLBACK
+      );
+    }
+    throw err;
+  }
 }
 var manageMembershipsSchema = z4.object({
   group_id: positiveId.describe(
@@ -534,7 +615,14 @@ var manageMembershipsSchema = z4.object({
   )
 });
 async function manageMemberships(input) {
-  return loomioPost("/b2/memberships", input);
+  try {
+    return await loomioPost("/b2/memberships", input);
+  } catch (err) {
+    if (err instanceof LoomioAuthError && err.status === 403) {
+      throw await explainForbidden(input.group_id, err, "membership changes");
+    }
+    throw err;
+  }
 }
 
 // src/tools/groups.ts
@@ -645,34 +733,79 @@ async function listGroups(input) {
 
 // src/tools/events.ts
 import { z as z6 } from "zod";
+var CONCURRENCY2 = 6;
+var EVENTS_PAGE_SIZE = 200;
+var MAX_EVENTS_PAGES = 10;
+var MAX_DISCUSSION_PAGES = 20;
+var MAX_SCAN_DISCUSSIONS = 500;
 var listEventsSchema = z6.object({
   discussion_id: positiveId.describe(
     "ID of the discussion whose event stream to fetch. Required \u2014 Loomio's v1/events endpoint silently returns empty without it."
   ),
-  limit: z6.number().int().min(1).max(200).optional().describe("Page size. Loomio defaults to 50; cap is 200."),
-  offset: z6.number().int().min(0).optional().describe("Page offset (Loomio's `from` parameter). Defaults to 0."),
+  limit: z6.number().int().min(1).max(200).optional().describe(
+    "Page size for a single-page fetch. Omit limit/offset to let the connector paginate the full discussion stream up to its bounded cap."
+  ),
+  offset: z6.number().int().min(0).optional().describe(
+    "Page offset (Loomio's `from` parameter). When supplied, list_events returns exactly that page instead of auto-paginating."
+  ),
   kinds: z6.array(z6.string().min(1)).optional().describe(
     "Optional filter to only these event kinds (applied client-side after fetch \u2014 Loomio doesn't filter `kind` server-side). Common kinds: new_discussion, new_comment, comment_edited, poll_created, stance_created, outcome_created, discussion_moved, discussion_closed, reaction."
   )
 });
+function mergeEventResponse(into, from) {
+  into.events = [...into.events ?? [], ...from.events ?? []];
+  into.comments = [...into.comments ?? [], ...from.comments ?? []];
+  into.users = [...into.users ?? [], ...from.users ?? []];
+  into.polls = [...into.polls ?? [], ...from.polls ?? []];
+  into.parent_events = [...into.parent_events ?? [], ...from.parent_events ?? []];
+  into.meta = from.meta ?? into.meta;
+}
+function filterKinds(resp, kinds) {
+  if (!kinds?.length) return resp;
+  const allowed = new Set(kinds);
+  return {
+    ...resp,
+    events: (resp.events ?? []).filter((e) => allowed.has(e.kind))
+  };
+}
 async function listEvents(input) {
-  const resp = await loomioGet("/v1/events", {
-    discussion_id: input.discussion_id,
-    ...input.limit !== void 0 ? { per: input.limit } : {},
-    ...input.offset !== void 0 ? { from: input.offset } : {}
-  });
-  if (input.kinds?.length) {
-    const allowed = new Set(input.kinds);
-    return {
-      ...resp,
-      events: (resp.events ?? []).filter((e) => allowed.has(e.kind))
-    };
+  if (input.limit !== void 0 || input.offset !== void 0) {
+    const resp = await loomioGet("/v1/events", {
+      discussion_id: input.discussion_id,
+      ...input.limit !== void 0 ? { per: input.limit } : {},
+      ...input.offset !== void 0 ? { from: input.offset } : {}
+    });
+    return filterKinds(resp, input.kinds);
   }
-  return resp;
+  const merged = {};
+  let offset = 0;
+  let pagesFetched = 0;
+  let truncated = false;
+  for (let page = 0; page < MAX_EVENTS_PAGES; page++) {
+    const resp = await loomioGet("/v1/events", {
+      discussion_id: input.discussion_id,
+      per: EVENTS_PAGE_SIZE,
+      from: offset
+    });
+    pagesFetched++;
+    const evs = resp.events ?? [];
+    mergeEventResponse(merged, resp);
+    if (evs.length < EVENTS_PAGE_SIZE) break;
+    offset += EVENTS_PAGE_SIZE;
+    if (page === MAX_EVENTS_PAGES - 1) truncated = true;
+  }
+  return filterKinds(
+    {
+      ...merged,
+      scope: {
+        complete: !truncated,
+        pages_fetched: pagesFetched,
+        events_truncated: truncated
+      }
+    },
+    input.kinds
+  );
 }
-var CONCURRENCY2 = 6;
-var EVENTS_PAGE_SIZE = 200;
-var MAX_EVENTS_PAGES = 10;
 var ACTIVITY_KINDS = /* @__PURE__ */ new Set([
   "new_discussion",
   "new_comment",
@@ -688,13 +821,27 @@ var getUserActivitySchema = z6.object({
   group_ids: z6.array(positiveId).min(1).max(50).describe(
     "Groups to scan. Required \u2014 pass the result of `list_groups` (or a subset of it) to make the cost explicit. ~1 outbound HTTP request per discussion in scope, plus one list_discussions call per group; ~100-300 calls is typical for a wide scan. Capped at 50 groups per call."
   ),
-  since: z6.string().optional().describe("ISO-8601 timestamp; ignore events before this time."),
-  until: z6.string().optional().describe("ISO-8601 timestamp; ignore events at or after this time.")
+  since: isoTimestamp.describe(
+    "ISO-8601 timestamp; ignore events before this time. Rejected if unparseable (so a typo can't silently widen the scan to all history)."
+  ),
+  until: isoTimestamp.describe(
+    "ISO-8601 timestamp; ignore events at or after this time. Rejected if unparseable."
+  )
+}).superRefine((input, ctx) => {
+  if (!input.since || !input.until) return;
+  if (Date.parse(input.until) <= Date.parse(input.since)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["until"],
+      message: "until must be later than since."
+    });
+  }
 });
 async function listDiscussionIdsForGroup(groupId) {
   const all = [];
   let offset = 0;
-  for (let page = 0; page < 20; page++) {
+  let truncated = false;
+  for (let page = 0; page < MAX_DISCUSSION_PAGES; page++) {
     const resp = await loomioGet("/b2/discussions", {
       group_id: groupId,
       status: "all",
@@ -705,12 +852,14 @@ async function listDiscussionIdsForGroup(groupId) {
     for (const d of ds) all.push({ id: d.id, group_id: groupId });
     if (ds.length < EVENTS_PAGE_SIZE) break;
     offset += EVENTS_PAGE_SIZE;
+    if (page === MAX_DISCUSSION_PAGES - 1) truncated = true;
   }
-  return all;
+  return { discussions: all, truncated };
 }
 async function fetchAllEventsForDiscussion(discussionId) {
   const all = [];
   let offset = 0;
+  let truncated = false;
   for (let page = 0; page < MAX_EVENTS_PAGES; page++) {
     const resp = await loomioGet("/v1/events", {
       discussion_id: discussionId,
@@ -721,10 +870,11 @@ async function fetchAllEventsForDiscussion(discussionId) {
     for (const e of evs) all.push(e);
     if (evs.length < EVENTS_PAGE_SIZE) break;
     offset += EVENTS_PAGE_SIZE;
+    if (page === MAX_EVENTS_PAGES - 1) truncated = true;
   }
-  return all;
+  return { events: all, truncated };
 }
-async function runWithConcurrency(items, worker, concurrency) {
+async function runWithConcurrency(items, worker, concurrency, recoverError = () => true) {
   const results = new Array(items.length).fill(null);
   let next = 0;
   async function take() {
@@ -733,7 +883,8 @@ async function runWithConcurrency(items, worker, concurrency) {
       if (i >= items.length) return;
       try {
         results[i] = await worker(items[i]);
-      } catch {
+      } catch (err) {
+        if (!recoverError(err)) throw err;
         results[i] = null;
       }
     }
@@ -741,26 +892,55 @@ async function runWithConcurrency(items, worker, concurrency) {
   await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, take));
   return results;
 }
+function isRecoverableScanError(err) {
+  if (err instanceof LoomioAuthError) return err.status === 403;
+  return err instanceof LoomioApiError;
+}
+function rememberRecentSample(samples, e) {
+  samples.push({
+    kind: e.kind,
+    discussion_id: e.discussion_id,
+    created_at: e.created_at,
+    eventable_type: e.eventable_type,
+    eventable_id: e.eventable_id
+  });
+  samples.sort((a, b) => Date.parse(b.created_at) - Date.parse(a.created_at));
+  if (samples.length > 10) samples.length = 10;
+}
 async function getUserActivity(input) {
   const groupIds = [...new Set(input.group_ids)];
   const groupDiscussionLists = await runWithConcurrency(
     groupIds,
     (gid) => listDiscussionIdsForGroup(gid),
-    CONCURRENCY2
+    CONCURRENCY2,
+    isRecoverableScanError
   );
+  const groupsFailed = [];
+  const groupsTruncated = [];
   const discussions = [];
-  for (const list of groupDiscussionLists) {
-    if (list) discussions.push(...list);
-  }
+  groupDiscussionLists.forEach((list, i) => {
+    if (list) {
+      discussions.push(...list.discussions);
+      if (list.truncated) groupsTruncated.push(groupIds[i]);
+    } else {
+      groupsFailed.push(groupIds[i]);
+    }
+  });
+  const discussionsCapped = discussions.length > MAX_SCAN_DISCUSSIONS;
+  const scanDiscussions = discussionsCapped ? discussions.slice(0, MAX_SCAN_DISCUSSIONS) : discussions;
   const since = input.since ? Date.parse(input.since) : Number.NEGATIVE_INFINITY;
   const until = input.until ? Date.parse(input.until) : Number.POSITIVE_INFINITY;
   let eventsExamined = 0;
+  let discussionsFailed = 0;
+  let discussionsTruncated = 0;
   const counts = {
     total: 0,
     new_discussion: 0,
     new_comment: 0,
+    comment_edited: 0,
     poll_created: 0,
     stance_created: 0,
+    stance_updated: 0,
     outcome_created: 0,
     reaction: 0,
     other: 0
@@ -771,12 +951,20 @@ async function getUserActivity(input) {
   let lastActivity = null;
   const samples = [];
   const eventStreams = await runWithConcurrency(
-    discussions,
-    async (d) => ({ groupId: d.group_id, events: await fetchAllEventsForDiscussion(d.id) }),
-    CONCURRENCY2
+    scanDiscussions,
+    async (d) => {
+      const { events, truncated } = await fetchAllEventsForDiscussion(d.id);
+      return { groupId: d.group_id, events, truncated };
+    },
+    CONCURRENCY2,
+    isRecoverableScanError
   );
   for (const s of eventStreams) {
-    if (!s) continue;
+    if (!s) {
+      discussionsFailed++;
+      continue;
+    }
+    if (s.truncated) discussionsTruncated++;
     for (const e of s.events) {
       eventsExamined++;
       if (e.actor_id !== input.user_id) continue;
@@ -794,25 +982,24 @@ async function getUserActivity(input) {
       byMonth[month] = (byMonth[month] ?? 0) + 1;
       if (!firstActivity || e.created_at < firstActivity) firstActivity = e.created_at;
       if (!lastActivity || e.created_at > lastActivity) lastActivity = e.created_at;
-      if (samples.length < 10) {
-        samples.push({
-          kind: e.kind,
-          discussion_id: e.discussion_id,
-          created_at: e.created_at,
-          eventable_type: e.eventable_type,
-          eventable_id: e.eventable_id
-        });
-      }
+      rememberRecentSample(samples, e);
     }
   }
+  const complete = groupsFailed.length === 0 && discussionsFailed === 0 && discussionsTruncated === 0 && groupsTruncated.length === 0 && !discussionsCapped;
   return {
     user_id: input.user_id,
     scope: {
       group_ids: groupIds,
-      discussions_scanned: discussions.length,
+      discussions_scanned: scanDiscussions.length,
       events_examined: eventsExamined,
       since: input.since ?? null,
-      until: input.until ?? null
+      until: input.until ?? null,
+      complete,
+      groups_failed: groupsFailed,
+      discussions_failed: discussionsFailed,
+      discussions_truncated: discussionsTruncated,
+      discussions_capped: discussionsCapped,
+      groups_truncated: groupsTruncated
     },
     counts,
     by_group: byGroup,
@@ -861,8 +1048,9 @@ function createLoomioMcpServer() {
   const b3Enabled = hasB3ApiKey();
   const server2 = new McpServer({
     name: "loomiomcp",
-    version: "0.1.0",
-    description: "MCP server for Loomio (loomio.com / self-hosted). Wraps Loomio's b2 public API: read and create discussions, polls, comments, plus list and manage group memberships. Read-only mode supported via LOOMIO_MCP_READONLY=1 (Cloud Run pattern). Optional b3 admin operations (deactivate / reactivate user) when LOOMIO_B3_API_KEY is set \u2014 instance operators only. Read tools annotated with readOnlyHint so MCP clients can auto-approve safe calls; destructive writes (manage_memberships with remove_absent, deactivate_user) carry destructiveHint.",
+    // Keep in sync with package.json on each release.
+    version: "0.0.6",
+    description: "MCP server for Loomio (loomio.com / self-hosted). Wraps Loomio's b2 public API: read and create discussions, polls, and comments; list and manage group memberships; read per-discussion event streams; and aggregate a user's participation across groups. Read-only mode supported via LOOMIO_MCP_READONLY=1 (Cloud Run pattern). Optional b3 admin operations (deactivate / reactivate user) when LOOMIO_B3_API_KEY is set \u2014 instance operators only. Read tools annotated with readOnlyHint so MCP clients can auto-approve safe calls; destructive writes (manage_memberships with remove_absent, deactivate_user) carry destructiveHint.",
     websiteUrl: "https://github.com/soil-dev/loomiomcp",
     icons: ICONS
   });
@@ -899,7 +1087,7 @@ function createLoomioMcpServer() {
   registerTool(
     server2,
     "list_polls",
-    "List polls in a Loomio group, ordered by creation date (newest first). Required: `group_id`. Optional `status` filter \u2014 'active' (default), 'closed', 'all' (every kept poll); `limit` 1-200 (default 50); `offset` for pagination. Caller must be a group member. Use to answer 'what's up for vote in group X', 'show me past poll results', or before create_poll to check what's already proposed.",
+    "List polls in a Loomio group, ordered by creation date (newest first). Required: `group_id`. Optional `status` filter \u2014 'active' (default), 'closed', 'all' (every kept poll); `limit` 1-200 (default 50); `offset` for pagination. Caller must be a group member. Use to answer 'what's up for vote in group X', 'show me past poll results', or before create_poll to check what's already proposed. FOR PER-USER PARTICIPATION QUESTIONS \u2014 'who voted', 'how often did X vote', 'compare members' turnout' \u2014 prefer `get_user_activity`. It returns participation directly (via the underlying events stream) and avoids the ambiguity between 'didn't vote' and 'abstained' that you can't tell apart from a `list_polls` response alone.",
     listPollsSchema,
     listPolls
   );
@@ -915,7 +1103,7 @@ function createLoomioMcpServer() {
   registerTool(
     server2,
     "list_memberships",
-    "List members of a Loomio group with their email addresses, roles, and join state. Required: `group_id`. Caller MUST be a group admin (non-admins get HTTP 403; the response is server-side scoped to include `include_email: true`). Optional `limit` 1-200 (default 50) and `offset` for pagination. Use to answer 'who's in group X', 'find a member by email', or \u2014 critically \u2014 BEFORE calling manage_memberships with remove_absent=true, since the diff between current and intended members is what makes that destructive call safe.",
+    "List members of a Loomio group with their email addresses, roles, and join state. Required: `group_id`. Caller MUST be a group admin (non-admins get HTTP 403; the response is server-side scoped to include `include_email: true`). Optional `limit` 1-200 (default 50) and `offset` for pagination. Use to answer 'who's in group X', 'find a member by email', or \u2014 critically \u2014 BEFORE calling manage_memberships with remove_absent=true, since the diff between current and intended members is what makes that destructive call safe. Do NOT use this tool to construct a participation analysis (e.g. 'how active is each member', 'who voted in our polls') by combining its output with `list_polls`. That reconstruction is more expensive in round-trips AND ambiguous about abstain-vs-didn't-vote. Use `get_user_activity` per member instead \u2014 it answers participation directly from the event stream.",
     listMembershipsSchema,
     listMemberships
   );
@@ -929,14 +1117,14 @@ function createLoomioMcpServer() {
   registerTool(
     server2,
     "list_events",
-    "Fetch the full event stream for one discussion \u2014 every new_comment, poll_created, stance_created, outcome_created, reaction, discussion_moved, etc. \u2014 with actor_id, kind, parent_id, created_at, and pointers to the underlying eventable record. Required: `discussion_id`. Optional `limit` (1-200, default 50), `offset` (Loomio's `from` param), and `kinds` (client-side filter to specific event kinds). The response also embeds related `comments`, `users`, and `polls` arrays for in-place resolution. Use this to answer 'show me the reply tree for thread X', 'who participated in discussion Y', or as the building block for cross-discussion aggregations. Loomio's v1/events endpoint requires a discussion_id; there's no instance-wide or per-user index \u2014 for user-centric questions, use `get_user_activity`.",
+    "Fetch the event stream for ONE discussion \u2014 new_comment, poll_created, stance_created, outcome_created, reaction, discussion_moved, etc. \u2014 with actor_id, kind, parent_id, created_at, and pointers to the underlying eventable record. Required: `discussion_id`. By default the connector paginates Loomio's v1/events endpoint up to a bounded cap and returns `scope.complete`; if you pass `limit` and/or `offset`, it returns exactly that one page. Optional `kinds` filters client-side after fetch. The response also embeds related `comments`, `users`, and `polls` arrays for in-place resolution. Use this to answer 'show me the reply tree for thread X', 'who participated in discussion Y', or as the building block for cross-discussion aggregations. Loomio's v1/events endpoint REQUIRES a discussion_id; there is no instance-wide, per-group, or per-user index. For user-centric questions across many discussions ('how active is X', 'compare members across groups'), use `get_user_activity` \u2014 do NOT loop `list_events` over every discussion yourself. `get_user_activity` does that fan-out server-side with concurrency control.",
     listEventsSchema,
     listEvents
   );
   registerTool(
     server2,
     "get_user_activity",
-    "Aggregate one user's activity across a set of groups. Server-side: fans out across every discussion in the specified groups, fetches its event stream, filters to events authored by the target user, and returns counts (by kind, by group, by month), plus first/last activity timestamps and a sample of recent events. Required: `user_id`, `group_ids` (1-50; pass the result of `list_groups` for instance-wide). Optional `since` / `until` (ISO-8601) bound the time window. Cost: one outbound HTTP call per discussion in scope (plus one `list_discussions` per group). Wide scans of an active instance commonly hit 100-300 calls in 5-30 seconds. Concurrency-capped at 6. Use this for 'tell me about user X', 'how active has user Y been in Q1', or before promoting/awarding someone. For one discussion at a time, use `list_events`.",
+    "Aggregate one user's activity across a set of groups. Server-side: fans out across every discussion in the specified groups, fetches its event stream, filters to events authored by the target user, and returns counts (by kind, by group, by month), plus first/last activity timestamps and a sample of recent events. Required: `user_id`, `group_ids` (1-50; pass the result of `list_groups` for instance-wide). Optional `since` / `until` (ISO-8601) bound the time window; `until` must be later than `since` when both are supplied. USE THIS for any user-centric question \u2014 single-user OR comparing multiple users. Examples that all map to this tool: 'tell me about user X', 'how active has Y been in Q1', 'compare participation across two groups (e.g. two teams or committees)', 'rank members of group N by participation', 'who's the most engaged contributor since June', 'build a participation card for each member'. For an N-user comparison, **call this tool N times** (once per user) \u2014 that's the intended pattern and is materially cheaper than reconstructing the same data from `list_polls` + `list_memberships`. Why call this instead of fanning out `list_polls`/`list_memberships` yourself: (1) Participation here is read from the canonical event stream \u2014 'voted' vs 'didn't vote' is unambiguous; you can't tell those apart from `list_polls` alone. (2) Round-trip count is the same or lower in aggregate, because each user's activity scan reuses the same `list_discussions` fetches in your conversation context. (3) The result is pre-aggregated by kind/group/month \u2014 Claude doesn't need to count anything client-side. Cost: one outbound HTTP call per discussion in scope (plus one `list_discussions` per group). A single user-activity call on a ~200-discussion instance is ~200 calls in 5-10 seconds, concurrency-capped at 6. That sounds large but is the correct denominator for comparison: building the same answer from `list_polls` requires the same discussion-scan + a separate `list_memberships` per group + client-side cross-referencing. The fan-out is bounded by a global cap, so a single call can't run away. COMPLETENESS: check `scope.complete`. When it's false the counts are a LOWER BOUND \u2014 inspect `scope.groups_failed` (groups the bot couldn't read, e.g. it isn't a member), `scope.groups_truncated` (a group's discussion listing hit the page cap), `scope.discussions_failed`, `scope.discussions_truncated` (very long threads), and `scope.discussions_capped` (scan hit the global ceiling). Report partial results as partial; don't present them as the whole picture. For one discussion at a time, use `list_events`. For 'what groups can the user see', use `list_groups` first to scope the call.",
     getUserActivitySchema,
     getUserActivity
   );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loomiomcp",
-  "version": "0.0.2",
-  "description": "Model Context Protocol server for Loomio. Lets Claude (Desktop, Code, or web Projects via Custom Connector) read and create Loomio discussions, polls, and group memberships in plain English.",
+  "version": "0.0.6",
+  "description": "Model Context Protocol server for Loomio. Lets Claude (Desktop, Code, or web Projects via Custom Connector) read and create Loomio discussions, polls, and comments, manage group memberships, and analyse member activity in plain English.",
   "keywords": [
     "mcp",
     "model-context-protocol",