capsulemcp 1.0.1 → 1.6.0

package/dist/index.js

@@ -5,6 +5,124 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/capsule/client.ts
 import { fetch } from "undici";
+
+// src/env.ts
+function readBool(name) {
+  const raw = process.env[name]?.toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+function readPositiveInt(name, fallback, min = 1) {
+  const raw = process.env[name];
+  if (raw === void 0 || raw === "") return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < min) return fallback;
+  return Math.floor(n);
+}
+
+// src/log.ts
+import { AsyncLocalStorage } from "async_hooks";
+function logVerbose() {
+  return readBool("CAPSULE_MCP_LOG_VERBOSE");
+}
+var chainHandlers = {
+  "tool.call": (ctx, f) => {
+    if (typeof f["tool"] === "string") ctx.tools.push(f["tool"]);
+  },
+  "capsule.request": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
+  // Cache-hit events feed the aggregate so the chain stat is right
+  // even on tools whose Capsule calls all hit the cache.
+  "cache.hit": (ctx) => {
+    ctx.cacheHits += 1;
+  }
+};
+function logEvent(event, fields, opts = {}) {
+  const ctx = requestContext.getStore();
+  if (ctx) chainHandlers[event]?.(ctx, fields);
+  if (!opts.force && !logVerbose()) return;
+  process.stderr.write(
+    `${JSON.stringify({ event, ...fields, timestamp: (/* @__PURE__ */ new Date()).toISOString() })}
+`
+  );
+}
+function redactPath(path) {
+  const noQuery = path.split("?")[0] ?? path;
+  return noQuery.replace(/\/\d+(?:,\d+)*/g, "/:id");
+}
+var requestContext = new AsyncLocalStorage();
+function getRequestContext() {
+  return requestContext.getStore();
+}
+
+// src/capsule/cache.ts
+var cache = /* @__PURE__ */ new Map();
+var MAX_ENTRIES = 64;
+var DEFAULT_TTL_MS = 5 * 60 * 1e3;
+function getCacheTtlMs() {
+  return readPositiveInt("CAPSULE_MCP_CACHE_TTL_MS", DEFAULT_TTL_MS, 0);
+}
+function explicitlyDisabled() {
+  return readBool("CAPSULE_MCP_CACHE_DISABLED");
+}
+function cacheDisabled() {
+  return explicitlyDisabled() || getCacheTtlMs() === 0;
+}
+function cacheKey(path, params) {
+  if (!params) return `GET ${path}`;
+  const entries = Object.entries(params).filter(([, v]) => v !== void 0);
+  if (entries.length === 0) return `GET ${path}`;
+  entries.sort(([a], [b]) => a.localeCompare(b));
+  const qs = entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&");
+  return `GET ${path}?${qs}`;
+}
+function cacheLookup(key) {
+  const entry = cache.get(key);
+  if (!entry) return { hit: false, reason: "empty" };
+  const now = Date.now();
+  if (entry.expiresAt < now) {
+    cache.delete(key);
+    return { hit: false, reason: "expired" };
+  }
+  return { hit: true, result: entry.result, ageMs: now - entry.storedAt };
+}
+function cacheSet(key, result) {
+  if (cacheDisabled()) return;
+  const ttl = getCacheTtlMs();
+  while (cache.size >= MAX_ENTRIES) {
+    const oldest = cache.keys().next().value;
+    if (oldest === void 0) break;
+    cache.delete(oldest);
+    const evictedKey = `GET ${redactPath(oldest.replace(/^GET /, ""))}`;
+    logEvent("cache.evict", { evictedKey, cacheSize: cache.size, reason: "cap" });
+  }
+  const now = Date.now();
+  cache.set(key, {
+    result,
+    storedAt: now,
+    expiresAt: now + ttl
+  });
+}
+function invalidateByPrefix(pathPrefix, trigger) {
+  const needle = `GET ${pathPrefix}`;
+  let droppedCount = 0;
+  for (const k of cache.keys()) {
+    if (k === needle || k.startsWith(`${needle}?`) || k.startsWith(`${needle}/`)) {
+      cache.delete(k);
+      droppedCount++;
+    }
+  }
+  if (droppedCount > 0) {
+    logEvent("cache.invalidate", {
+      prefix: pathPrefix,
+      droppedCount,
+      cacheSize: cache.size,
+      ...trigger ? { trigger } : {}
+    });
+  }
+}
+
+// src/capsule/client.ts
 var DEFAULT_BASE_URL = "https://api.capsulecrm.com/api/v2";
 function baseUrl() {
   const override = process.env["CAPSULE_API_BASE_URL"];
@@ -24,8 +142,7 @@ function baseUrl() {
   return override;
 }
 function isReadOnly() {
-  const v = process.env["CAPSULE_MCP_READONLY"]?.toLowerCase();
-  return v === "1" || v === "true" || v === "yes";
+  return readBool("CAPSULE_MCP_READONLY");
 }
 var CapsuleReadOnlyError = class extends Error {
   constructor(method) {
@@ -154,6 +271,8 @@ async function fetchWithTimeout(url, options) {
   }
 }
 async function doFetch(url, options) {
+  const startedAt = Date.now();
+  const method = options?.method ?? "GET";
   const first = await fetchWithTimeout(url, options);
   if (first.res.status === 429) {
     const delay = parseRateLimitDelay(first.res);
@@ -167,10 +286,30 @@ async function doFetch(url, options) {
         "Rate limit exceeded after one retry. Please slow down your requests."
       );
     }
+    emitCapsuleRequest(method, url, retried.res, Date.now() - startedAt, true);
     return retried;
   }
+  emitCapsuleRequest(method, url, first.res, Date.now() - startedAt, false);
   return first;
 }
+function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
+  let path = "";
+  try {
+    path = redactPath(new URL(url).pathname);
+  } catch {
+    path = "?";
+  }
+  const lenHeader = res.headers.get("content-length");
+  const responseBytes = lenHeader ? Number.parseInt(lenHeader, 10) : 0;
+  logEvent("capsule.request", {
+    method,
+    path,
+    status: res.status,
+    durationMs,
+    responseBytes: Number.isFinite(responseBytes) ? responseBytes : 0,
+    ...retriedAfter429 ? { retriedAfter429: true } : {}
+  });
+}
 async function throwForStatus(res) {
   if (res.status === 401) {
     const detail = await parseErrorBody(res);
@@ -210,6 +349,34 @@ async function capsuleGet(path, params) {
     cleanup();
   }
 }
+async function capsuleGetCached(path, params) {
+  if (cacheDisabled()) return capsuleGet(path, params);
+  const key = cacheKey(path, params);
+  const lookup = cacheLookup(key);
+  if (lookup.hit) {
+    if (logVerbose()) {
+      logEvent("cache.hit", {
+        path: redactPath(path),
+        ...params ? { paramFields: Object.keys(params) } : {},
+        ageMs: lookup.ageMs
+      });
+    }
+    return lookup.result;
+  }
+  const fetchStart = Date.now();
+  const result = await capsuleGet(path, params);
+  const latencyMs = Date.now() - fetchStart;
+  cacheSet(key, result);
+  if (logVerbose()) {
+    logEvent("cache.miss", {
+      path: redactPath(path),
+      ...params ? { paramFields: Object.keys(params) } : {},
+      reason: lookup.reason,
+      latencyMs
+    });
+  }
+  return result;
+}
 async function capsulePost(path, body) {
   if (isReadOnly()) throw new CapsuleReadOnlyError("POST");
   const token = getToken();
@@ -396,7 +563,195 @@ var ICONS = [
   }
 ];
 
+// src/tasks/store.ts
+import { InMemoryTaskStore } from "@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js";
+import {
+  ErrorCode,
+  McpError
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/tasks/config.ts
+var DEFAULT_TTL_MS2 = 5 * 60 * 1e3;
+var DEFAULT_MAX_KEEP_ALIVE_MS = 15 * 60 * 1e3;
+var MIN_TASK_TTL_MS = 1e3;
+var DEFAULT_POLL_FREQUENCY_MS = 1500;
+var MIN_POLL_FREQUENCY_MS = 500;
+var DEFAULT_MAX_PER_CLIENT = 20;
+var DEFAULT_MAX_TOTAL = 200;
+function getTasksConfig() {
+  const enabled = readBool("MCP_TASKS_ENABLED");
+  const maxKeepAliveMs = Math.max(
+    readPositiveInt("MCP_TASKS_MAX_KEEP_ALIVE_MS", DEFAULT_MAX_KEEP_ALIVE_MS),
+    MIN_TASK_TTL_MS
+  );
+  const defaultTtlMs = Math.min(
+    Math.max(readPositiveInt("MCP_TASKS_DEFAULT_TTL_MS", DEFAULT_TTL_MS2), MIN_TASK_TTL_MS),
+    maxKeepAliveMs
+  );
+  const defaultPollFrequencyMs = Math.max(
+    readPositiveInt("MCP_TASKS_DEFAULT_POLL_FREQUENCY_MS", DEFAULT_POLL_FREQUENCY_MS),
+    MIN_POLL_FREQUENCY_MS
+  );
+  const maxPerClient = readPositiveInt("MCP_TASKS_MAX_PER_CLIENT", DEFAULT_MAX_PER_CLIENT);
+  const maxTotal = readPositiveInt("MCP_TASKS_MAX_TOTAL", DEFAULT_MAX_TOTAL);
+  return {
+    enabled,
+    defaultTtlMs,
+    maxKeepAliveMs,
+    defaultPollFrequencyMs,
+    maxPerClient,
+    maxTotal
+  };
+}
+
+// src/tasks/store.ts
+var _globalStore = null;
+function getGlobalStore() {
+  if (_globalStore === null) {
+    _globalStore = new InMemoryTaskStore();
+  }
+  return _globalStore;
+}
+var owners = /* @__PURE__ */ new Map();
+var abortControllers = /* @__PURE__ */ new Map();
+function registerAbortController(taskId, controller) {
+  abortControllers.set(taskId, controller);
+}
+function countPerClient(clientId) {
+  let n = 0;
+  for (const owner of owners.values()) {
+    if (owner === clientId) n++;
+  }
+  return n;
+}
+function createScopedTaskStore(clientId) {
+  if (!clientId) {
+    throw new Error("createScopedTaskStore: clientId is required");
+  }
+  const global = getGlobalStore();
+  async function getOwned(taskId) {
+    if (owners.get(taskId) !== clientId) return null;
+    return global.getTask(taskId);
+  }
+  return {
+    async createTask(taskParams, requestId, request, sessionId) {
+      const cfg = getTasksConfig();
+      const totalNow = owners.size;
+      if (totalNow >= cfg.maxTotal) {
+        logEvent("task.rejected", {
+          reason: "max_total",
+          clientId,
+          totalNow,
+          cap: cfg.maxTotal
+        });
+        throw new McpError(ErrorCode.InvalidParams, "Task quota exceeded for this server instance");
+      }
+      const perClientNow = countPerClient(clientId);
+      if (perClientNow >= cfg.maxPerClient) {
+        logEvent("task.rejected", {
+          reason: "max_per_client",
+          clientId,
+          perClientNow,
+          cap: cfg.maxPerClient
+        });
+        throw new McpError(ErrorCode.InvalidParams, "Task quota exceeded for this client");
+      }
+      const requestedTtl = taskParams.ttl;
+      const clampedTtl = requestedTtl === null ? cfg.maxKeepAliveMs : Math.max(
+        MIN_TASK_TTL_MS,
+        Math.min(requestedTtl ?? cfg.defaultTtlMs, cfg.maxKeepAliveMs)
+      );
+      const requestedPoll = taskParams.pollInterval ?? cfg.defaultPollFrequencyMs;
+      const clampedPoll = Math.max(cfg.defaultPollFrequencyMs, Math.floor(requestedPoll));
+      const task = await global.createTask(
+        { ttl: clampedTtl, pollInterval: clampedPoll, context: taskParams.context },
+        requestId,
+        request,
+        sessionId
+      );
+      owners.set(task.taskId, clientId);
+      const timer = setTimeout(() => {
+        owners.delete(task.taskId);
+        abortControllers.delete(task.taskId);
+        logEvent("task.evicted", { taskId: task.taskId, clientId, reason: "ttl" });
+      }, clampedTtl);
+      timer.unref?.();
+      logEvent("task.created", {
+        taskId: task.taskId,
+        clientId,
+        ttl: clampedTtl,
+        pollInterval: clampedPoll,
+        method: typeof request.method === "string" ? request.method : "unknown"
+      });
+      return task;
+    },
+    async getTask(taskId) {
+      return getOwned(taskId);
+    },
+    async storeTaskResult(taskId, status, result, sessionId) {
+      if (owners.get(taskId) !== clientId) {
+        throw new McpError(ErrorCode.InvalidParams, "Task not found");
+      }
+      logEvent("task.transition", { taskId, clientId, status });
+      await global.storeTaskResult(taskId, status, result, sessionId);
+    },
+    async getTaskResult(taskId, sessionId) {
+      if (owners.get(taskId) !== clientId) {
+        throw new McpError(ErrorCode.InvalidParams, "Task not found");
+      }
+      return global.getTaskResult(taskId, sessionId);
+    },
+    async updateTaskStatus(taskId, status, statusMessage, sessionId) {
+      if (owners.get(taskId) !== clientId) {
+        throw new McpError(ErrorCode.InvalidParams, "Task not found");
+      }
+      logEvent("task.transition", { taskId, clientId, status, statusMessage });
+      await global.updateTaskStatus(taskId, status, statusMessage, sessionId);
+      if (status === "cancelled") {
+        const ctrl = abortControllers.get(taskId);
+        if (ctrl && !ctrl.signal.aborted) ctrl.abort();
+      }
+      if (status === "completed" || status === "failed" || status === "cancelled") {
+        abortControllers.delete(taskId);
+      }
+    },
+    async listTasks(cursor, sessionId) {
+      const page = await global.listTasks(cursor, sessionId);
+      const filtered = page.tasks.filter((t) => owners.get(t.taskId) === clientId);
+      return page.nextCursor ? { tasks: filtered, nextCursor: page.nextCursor } : { tasks: filtered };
+    }
+  };
+}
+
 // src/server/register-tool.ts
+var READ_PREFIXES = ["search_", "filter_", "get_", "list_", "show_", "run_"];
+var DESTRUCTIVE_NON_DELETE = /* @__PURE__ */ new Set(["remove_track", "remove_additional_party"]);
+function isDestructive(name) {
+  return name.startsWith("delete_") || DESTRUCTIVE_NON_DELETE.has(name);
+}
+function inferAnnotations(name) {
+  if (READ_PREFIXES.some((p) => name.startsWith(p))) {
+    return { readOnlyHint: true };
+  }
+  if (isDestructive(name)) {
+    return { destructiveHint: true };
+  }
+  return void 0;
+}
+function argFieldNames(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) return [];
+  return Object.keys(input);
+}
+function emitToolCall(opts) {
+  logEvent("tool.call", {
+    tool: opts.tool,
+    ...opts.clientId ? { clientId: opts.clientId } : {},
+    argFields: opts.argFields,
+    durationMs: Date.now() - opts.startedAt,
+    outcome: opts.outcome,
+    ...opts.taskAugmented ? { taskAugmented: true } : {}
+  });
+}
 function wrapAsText(result) {
   return {
     content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
@@ -404,10 +759,93 @@ function wrapAsText(result) {
 }
 function registerTool(server2, name, description, schema, handler) {
   const registerWithSchema = server2.registerTool.bind(server2);
-  registerWithSchema(name, { description, inputSchema: schema }, async (input) => {
-    const result = await handler(input);
-    return wrapAsText(result);
-  });
+  const annotations = inferAnnotations(name);
+  registerWithSchema(
+    name,
+    { description, inputSchema: schema, ...annotations ? { annotations } : {} },
+    async (input) => {
+      const startedAt = Date.now();
+      const argFields = argFieldNames(input);
+      const clientId = getRequestContext()?.clientId;
+      try {
+        const result = await handler(input);
+        emitToolCall({ tool: name, clientId, argFields, startedAt, outcome: "success" });
+        return wrapAsText(result);
+      } catch (err) {
+        emitToolCall({ tool: name, clientId, argFields, startedAt, outcome: "error" });
+        throw err;
+      }
+    }
+  );
+}
+function registerToolTask(server2, name, description, schema, handler) {
+  const registerWithSchema = server2.experimental.tasks.registerToolTask.bind(
+    server2.experimental.tasks
+  );
+  const annotations = inferAnnotations(name);
+  registerWithSchema(
+    name,
+    {
+      description,
+      inputSchema: schema,
+      execution: { taskSupport: "optional" },
+      ...annotations ? { annotations } : {}
+    },
+    {
+      createTask: async (input, extra) => {
+        const task = await extra.taskStore.createTask({
+          ttl: extra.taskRequestedTtl
+        });
+        const abortController = new AbortController();
+        registerAbortController(task.taskId, abortController);
+        const requestClientId = getRequestContext()?.clientId;
+        const argFields = argFieldNames(input);
+        void (async () => {
+          if (abortController.signal.aborted) return;
+          try {
+            await extra.taskStore.updateTaskStatus(task.taskId, "working");
+          } catch {
+          }
+          const handlerStart = Date.now();
+          let payload;
+          let outcome = "success";
+          try {
+            const result = await handler(input, {
+              signal: abortController.signal
+            });
+            payload = wrapAsText(result);
+          } catch (err) {
+            if (abortController.signal.aborted) return;
+            outcome = "error";
+            const message = err instanceof Error ? err.message : String(err);
+            payload = {
+              content: [{ type: "text", text: message }],
+              isError: true
+            };
+          }
+          emitToolCall({
+            tool: name,
+            clientId: requestClientId,
+            argFields,
+            startedAt: handlerStart,
+            outcome,
+            taskAugmented: true
+          });
+          if (abortController.signal.aborted) return;
+          try {
+            await extra.taskStore.storeTaskResult(task.taskId, "completed", payload);
+          } catch {
+          }
+        })();
+        return { task };
+      },
+      getTask: async (_input, extra) => extra.taskStore.getTask(extra.taskId),
+      getTaskResult: async (_input, extra) => {
+        const r = await extra.taskStore.getTaskResult(extra.taskId);
+        return r;
+      }
+    }
+  );
 }
 
 // src/tools/parties.ts
@@ -424,6 +862,98 @@ function confirmFlag() {
   return z.literal(true, { error: () => CONFIRM_REQUIRED_MESSAGE });
 }
 
+// src/capsule/batch.ts
+function chunk(arr, size) {
+  if (size <= 0) throw new Error("chunk size must be positive");
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) {
+    out.push(arr.slice(i, i + size));
+  }
+  return out;
+}
+var DEFAULT_CONCURRENCY = 5;
+var MAX_CONCURRENCY = 50;
+function getBatchConcurrency() {
+  return Math.min(
+    readPositiveInt("CAPSULE_MCP_BATCH_CONCURRENCY", DEFAULT_CONCURRENCY),
+    MAX_CONCURRENCY
+  );
+}
+async function batchExecute(tool, items, action, options = {}) {
+  const concurrency = getBatchConcurrency();
+  const results = new Array(items.length);
+  const startedAt = Date.now();
+  const signal = options.signal;
+  let cursor = 0;
+  async function worker() {
+    while (true) {
+      const i = cursor;
+      cursor += 1;
+      if (i >= items.length) return;
+      if (signal?.aborted) {
+        results[i] = {
+          ok: false,
+          error: { message: "cancelled by tasks/cancel" }
+        };
+        continue;
+      }
+      try {
+        const result = await action(items[i], i);
+        results[i] = { ok: true, result };
+      } catch (err) {
+        results[i] = { ok: false, error: extractError(err) };
+      }
+    }
+  }
+  const workers = [];
+  for (let w = 0; w < Math.min(concurrency, items.length); w++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  const succeeded = results.filter((r) => r.ok).length;
+  const failed = results.length - succeeded;
+  const summary = { total: results.length, succeeded, failed };
+  const failureReasons = logVerbose() ? topFailureReasons(results, 5) : [];
+  logEvent(
+    "batch.complete",
+    {
+      tool,
+      total: summary.total,
+      succeeded: summary.succeeded,
+      failed: summary.failed,
+      durationMs: Date.now() - startedAt,
+      concurrency,
+      ...failureReasons.length > 0 ? { failureReasons } : {}
+    },
+    { force: true }
+  );
+  return { results, summary };
+}
+function extractError(err) {
+  if (err instanceof Error) {
+    const maybeStatus = err.status;
+    return {
+      ...typeof maybeStatus === "number" ? { status: maybeStatus } : {},
+      message: err.message
+    };
+  }
+  return { message: String(err) };
+}
+function topFailureReasons(results, n) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    if (r.ok) continue;
+    const key = `${r.error.status ?? "?"}::${r.error.message}`;
+    const existing = counts.get(key);
+    if (existing) {
+      existing.count += 1;
+    } else {
+      counts.set(key, { ...r.error, count: 1 });
+    }
+  }
+  return Array.from(counts.values()).sort((a, b) => b.count - a.count).slice(0, n);
+}
+
 // src/capsule/idempotent.ts
 var isCapsule404 = (err) => err instanceof CapsuleApiError && err.status === 404;
 var isCapsuleTagNotFound = (err) => err instanceof CapsuleApiError && err.status === 422 && /tag not found/i.test(err.message);
@@ -562,14 +1092,26 @@ async function getParty(input) {
   return data;
 }
 var getPartiesSchema = z3.object({
-  ids: z3.array(z3.number().int().positive()).min(1).max(10).describe("Array of party IDs (1\u201310). Capsule caps batch fetches at 10."),
+  ids: z3.array(z3.number().int().positive()).min(1).max(50).describe(
+    "Array of party IDs (1\u201350). Capsule's native batch-fetch endpoint caps at 10 per request; the connector transparently splits larger sets into 10-id chunks and fans out the Capsule calls in parallel. Result shape is identical regardless of input size."
+  ),
   embed: z3.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getParties(input) {
-  const { data } = await capsuleGet(`/parties/${input.ids.join(",")}`, {
-    embed: input.embed
-  });
-  return data;
+  const { ids, embed } = input;
+  if (ids.length <= 10) {
+    const { data } = await capsuleGet(`/parties/${ids.join(",")}`, {
+      embed
+    });
+    return data;
+  }
+  const chunks = chunk(ids, 10);
+  const responses = await Promise.all(
+    chunks.map(
+      (chunkIds) => capsuleGet(`/parties/${chunkIds.join(",")}`, { embed })
+    )
+  );
+  return { parties: responses.flatMap((r) => r.data.parties) };
 }
 var listPartyOpportunitiesSchema = z3.object({
   partyId: z3.number().int().positive(),
@@ -653,6 +1195,14 @@ async function updateParty(input) {
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePut(`/parties/${id}`, { party: body });
 }
+var batchUpdatePartySchema = z3.object({
+  items: z3.array(updatePartySchema).min(1).max(50).describe(
+    "Array of 1\u201350 update_party inputs. Each item is the same shape as a single update_party call \u2014 id is required, every other field is optional. Capped at 50 so a single tool call can't burn an outsized share of Capsule's hourly per-token rate budget (~4000 req/h)."
+  )
+});
+async function batchUpdateParty(input, opts = {}) {
+  return batchExecute("batch_update_party", input.items, (item) => updateParty(item), opts);
+}
 var deletePartySchema = z3.object({
   id: z3.number().int().positive(),
   confirm: confirmFlag().describe(
@@ -855,15 +1405,29 @@ async function getOpportunity(input) {
   return data;
 }
 var getOpportunitiesSchema = z4.object({
-  ids: z4.array(z4.number().int().positive()).min(1).max(10).describe("Array of opportunity IDs (1\u201310). Capsule caps batch fetches at 10."),
+  ids: z4.array(z4.number().int().positive()).min(1).max(50).describe(
+    "Array of opportunity IDs (1\u201350). Capsule's native batch-fetch endpoint caps at 10 per request; the connector transparently splits larger sets into 10-id chunks and fans out the Capsule calls in parallel."
+  ),
   embed: z4.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getOpportunities(input) {
-  const { data } = await capsuleGet(
-    `/opportunities/${input.ids.join(",")}`,
-    { embed: input.embed }
+  const { ids, embed } = input;
+  if (ids.length <= 10) {
+    const { data } = await capsuleGet(
+      `/opportunities/${ids.join(",")}`,
+      { embed }
+    );
+    return data;
+  }
+  const chunks = chunk(ids, 10);
+  const responses = await Promise.all(
+    chunks.map(
+      (chunkIds) => capsuleGet(`/opportunities/${chunkIds.join(",")}`, {
+        embed
+      })
+    )
   );
-  return data;
+  return { opportunities: responses.flatMap((r) => r.data.opportunities) };
 }
 var createOpportunitySchema = z4.object({
   name: z4.string().min(1),
@@ -924,6 +1488,19 @@ async function updateOpportunity(input) {
     opportunity: body
   });
 }
+var batchUpdateOpportunitySchema = z4.object({
+  items: z4.array(updateOpportunitySchema).min(1).max(50).describe(
+    "Array of 1\u201350 update_opportunity inputs. Each item is the same shape as a single update_opportunity call \u2014 id is required, every other field is optional. Capped at 50 so a single tool call can't burn an outsized share of Capsule's hourly per-token rate budget."
+  )
+});
+async function batchUpdateOpportunity(input, opts = {}) {
+  return batchExecute(
+    "batch_update_opportunity",
+    input.items,
+    (item) => updateOpportunity(item),
+    opts
+  );
+}
 var deleteOpportunitySchema = z4.object({
   id: z4.number().int().positive(),
   confirm: confirmFlag().describe(
@@ -969,14 +1546,26 @@ async function getProject(input) {
   return data;
 }
 var getProjectsSchema = z5.object({
-  ids: z5.array(z5.number().int().positive()).min(1).max(10).describe("Array of project IDs (1\u201310). Capsule caps batch fetches at 10."),
+  ids: z5.array(z5.number().int().positive()).min(1).max(50).describe(
+    "Array of project IDs (1\u201350). Capsule's native batch-fetch endpoint caps at 10 per request; the connector transparently splits larger sets into 10-id chunks and fans out the Capsule calls in parallel."
+  ),
   embed: z5.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getProjects(input) {
-  const { data } = await capsuleGet(`/kases/${input.ids.join(",")}`, {
-    embed: input.embed
-  });
-  return data;
+  const { ids, embed } = input;
+  if (ids.length <= 10) {
+    const { data } = await capsuleGet(`/kases/${ids.join(",")}`, {
+      embed
+    });
+    return data;
+  }
+  const chunks = chunk(ids, 10);
+  const responses = await Promise.all(
+    chunks.map(
+      (chunkIds) => capsuleGet(`/kases/${chunkIds.join(",")}`, { embed })
+    )
+  );
+  return { kases: responses.flatMap((r) => r.data.kases) };
 }
 var createProjectSchema = z5.object({
   name: z5.string().min(1),
@@ -1104,11 +1693,21 @@ async function getTask(input) {
   return data;
 }
 var getTasksSchema = z6.object({
-  ids: z6.array(z6.number().int().positive()).min(1).max(10).describe("Array of task IDs (1\u201310). Capsule caps batch fetches at 10.")
+  ids: z6.array(z6.number().int().positive()).min(1).max(50).describe(
+    "Array of task IDs (1\u201350). Capsule's native batch-fetch endpoint caps at 10 per request; the connector transparently splits larger sets into 10-id chunks and fans out the Capsule calls in parallel."
+  )
 });
 async function getTasks(input) {
-  const { data } = await capsuleGet(`/tasks/${input.ids.join(",")}`);
-  return data;
+  const { ids } = input;
+  if (ids.length <= 10) {
+    const { data } = await capsuleGet(`/tasks/${ids.join(",")}`);
+    return data;
+  }
+  const chunks = chunk(ids, 10);
+  const responses = await Promise.all(
+    chunks.map((chunkIds) => capsuleGet(`/tasks/${chunkIds.join(",")}`))
+  );
+  return { tasks: responses.flatMap((r) => r.data.tasks) };
 }
 var createTaskSchema = z6.object({
   description: z6.string().min(1),
@@ -1168,6 +1767,14 @@ async function completeTask(input) {
     task: { status: "COMPLETED" }
   });
 }
+var batchCompleteTaskSchema = z6.object({
+  ids: z6.array(z6.number().int().positive()).min(1).max(50).describe(
+    "Array of 1\u201350 task ids to mark COMPLETED in parallel. Each id resolves to one PUT /tasks/{id}; failures (e.g. 404 for a deleted task) surface per-item in the result array, the rest still complete. Capped at 50."
+  )
+});
+async function batchCompleteTask(input, opts = {}) {
+  return batchExecute("batch_complete_task", input.ids, (id) => completeTask({ id }), opts);
+}
 var deleteTaskSchema = z6.object({
   id: z6.number().int().positive(),
   confirm: confirmFlag().describe(
@@ -1314,7 +1921,7 @@ var paginationFields = {
 };
 var listPipelinesSchema = z8.object({ ...paginationFields });
 async function listPipelines(input) {
-  const { data, nextPage } = await capsuleGet("/pipelines", {
+  const { data, nextPage } = await capsuleGetCached("/pipelines", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
@@ -1325,7 +1932,7 @@ var listMilestonesSchema = z8.object({
   ...paginationFields
 });
 async function listMilestones(input) {
-  const { data, nextPage } = await capsuleGet(
+  const { data, nextPage } = await capsuleGetCached(
     `/pipelines/${input.pipelineId}/milestones`,
     { page: input.page ?? 1, perPage: input.perPage ?? 100 }
   );
@@ -1340,7 +1947,7 @@ var paginationFields2 = {
 };
 var listBoardsSchema = z9.object({ ...paginationFields2 });
 async function listBoards(input) {
-  const { data, nextPage } = await capsuleGet("/boards", {
+  const { data, nextPage } = await capsuleGetCached("/boards", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
@@ -1354,7 +1961,7 @@ var listStagesSchema = z9.object({
 });
 async function listStages(input) {
   const path = input.boardId !== void 0 ? `/boards/${input.boardId}/stages` : "/stages";
-  const { data, nextPage } = await capsuleGet(path, {
+  const { data, nextPage } = await capsuleGetCached(path, {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
@@ -1381,7 +1988,7 @@ var listTagsSchema = z10.object({
 });
 async function listTags(input) {
   const path = TAG_LIST_PATH[input.entity];
-  const { data, nextPage } = await capsuleGet(path, {
+  const { data, nextPage } = await capsuleGetCached(path, {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
@@ -1397,9 +2004,11 @@ var addTagSchema = z10.object({
 async function addTag(input) {
   const { entity, entityId, tagName } = input;
   const wrapper = ENTITY_TO_WRAPPER[entity];
-  return capsulePut(`/${entity}/${entityId}`, {
+  const result = await capsulePut(`/${entity}/${entityId}`, {
     [wrapper]: { tags: [{ name: tagName }] }
   });
+  invalidateByPrefix(TAG_LIST_PATH[entity], "add_tag");
+  return result;
 }
 var removeTagByIdSchema = z10.object({
   entity: TagEntity,
@@ -1411,17 +2020,17 @@ var removeTagByIdSchema = z10.object({
 async function removeTagById(input) {
   const { entity, entityId, tagId } = input;
   const wrapper = ENTITY_TO_WRAPPER[entity];
-  return idempotentWithResult(
+  const result = await idempotentWithResult(
     () => capsulePut(`/${entity}/${entityId}`, {
       [wrapper]: { tags: [{ id: tagId, _delete: true }] }
     }),
-    (result) => ({
+    (result2) => ({
       removed: true,
       alreadyRemoved: false,
       entity,
       entityId,
       tagId,
-      ...result
+      ...result2
     }),
     () => ({ removed: true, alreadyRemoved: true, entity, entityId, tagId }),
     // Tag detach uses PUT with _delete: true and 422s with "tag not
@@ -1429,6 +2038,24 @@ async function removeTagById(input) {
     // 404. Other 422s with different wording still surface.
     isCapsuleTagNotFound
   );
+  invalidateByPrefix(TAG_LIST_PATH[entity], "remove_tag_by_id");
+  return result;
+}
+var batchAddTagSchema = z10.object({
+  items: z10.array(addTagSchema).min(1).max(50).describe(
+    "Array of 1\u201350 add_tag inputs. Useful for mass-tagging \u2014 e.g. 'tag these 20 contacts as RSAC26'. Each item is the same shape as a single add_tag call. The list_tags cache is invalidated for each affected entity type. Capped at 50."
+  )
+});
+async function batchAddTag(input, opts = {}) {
+  return batchExecute("batch_add_tag", input.items, (item) => addTag(item), opts);
+}
+var batchRemoveTagByIdSchema = z10.object({
+  items: z10.array(removeTagByIdSchema).min(1).max(50).describe(
+    "Array of 1\u201350 remove_tag_by_id inputs. Each item is the same shape as a single remove_tag_by_id call. Detaches the tag from each specified entity; the tag definition itself persists in the tenant. Capped at 50."
+  )
+});
+async function batchRemoveTagById(input, opts = {}) {
+  return batchExecute("batch_remove_tag_by_id", input.items, (item) => removeTagById(item), opts);
 }
 
 // src/tools/users.ts
@@ -1438,7 +2065,7 @@ var listUsersSchema = z11.object({
   perPage: z11.number().int().min(1).max(100).optional()
 });
 async function listUsers(input) {
-  const { data, nextPage } = await capsuleGet("/users", {
+  const { data, nextPage } = await capsuleGetCached("/users", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
@@ -1507,7 +2134,7 @@ var paginationFields3 = {
 };
 var listTeamsSchema = z13.object({ ...paginationFields3 });
 async function listTeams(input) {
-  const { data, nextPage } = await capsuleGet("/teams", {
+  const { data, nextPage } = await capsuleGetCached("/teams", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
@@ -1515,7 +2142,7 @@ async function listTeams(input) {
 }
 var listLostReasonsSchema = z13.object({ ...paginationFields3 });
 async function listLostReasons(input) {
-  const { data, nextPage } = await capsuleGet("/lostreasons", {
+  const { data, nextPage } = await capsuleGetCached("/lostreasons", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
@@ -1523,20 +2150,23 @@ async function listLostReasons(input) {
 }
 var listActivityTypesSchema = z13.object({ ...paginationFields3 });
 async function listActivityTypes(input) {
-  const { data, nextPage } = await capsuleGet("/activitytypes", {
-    page: input.page ?? 1,
-    perPage: input.perPage ?? 100
-  });
+  const { data, nextPage } = await capsuleGetCached(
+    "/activitytypes",
+    {
+      page: input.page ?? 1,
+      perPage: input.perPage ?? 100
+    }
+  );
   return { ...data, nextPage };
 }
 var getSiteSchema = z13.object({});
 async function getSite(_input) {
-  const { data } = await capsuleGet("/site");
+  const { data } = await capsuleGetCached("/site");
   return data;
 }
 var listTrackDefinitionsSchema = z13.object({ ...paginationFields3 });
 async function listTrackDefinitions(input) {
-  const { data, nextPage } = await capsuleGet(
+  const { data, nextPage } = await capsuleGetCached(
     "/trackdefinitions",
     { page: input.page ?? 1, perPage: input.perPage ?? 100 }
   );
@@ -1544,7 +2174,7 @@ async function listTrackDefinitions(input) {
 }
 var listCategoriesSchema = z13.object({ ...paginationFields3 });
 async function listCategories(input) {
-  const { data, nextPage } = await capsuleGet("/categories", {
+  const { data, nextPage } = await capsuleGetCached("/categories", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
@@ -1552,7 +2182,7 @@ async function listCategories(input) {
 }
 var listGoalsSchema = z13.object({ ...paginationFields3 });
 async function listGoals(input) {
-  const { data, nextPage } = await capsuleGet("/goals", {
+  const { data, nextPage } = await capsuleGetCached("/goals", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
@@ -1711,7 +2341,7 @@ var listCustomFieldsSchema = z16.object({
   entity: CustomFieldEntity
 });
 async function listCustomFields(input) {
-  const { data } = await capsuleGet(
+  const { data } = await capsuleGetCached(
     `/${input.entity}/fields/definitions`
   );
   return data;
@@ -1721,7 +2351,7 @@ var getCustomFieldSchema = z16.object({
   fieldId: z16.number().int().positive().describe("Custom field definition id.")
 });
 async function getCustomField(input) {
-  const { data } = await capsuleGet(
+  const { data } = await capsuleGetCached(
     `/${input.entity}/fields/definitions/${input.fieldId}`
   );
   return data;
@@ -1892,7 +2522,7 @@ var listSavedFiltersSchema = z19.object({
   entity: EntitySchema
 });
 async function listSavedFilters(input) {
-  const { data } = await capsuleGet(`/${input.entity}/filters`);
+  const { data } = await capsuleGetCached(`/${input.entity}/filters`);
   return data;
 }
 var runSavedFilterSchema = z19.object({
@@ -1911,15 +2541,35 @@ async function runSavedFilter(input) {
 }
 
 // src/server.ts
-function createCapsuleMcpServer() {
+function createCapsuleMcpServer(opts) {
   const readOnly = isReadOnly();
-  const server2 = new McpServer({
-    name: "capsulemcp",
-    version: "1.0.1",
-    description: "Read and (optionally) modify Capsule CRM data \u2014 parties, opportunities, projects, tasks, timeline entries, pipelines, tags.",
-    websiteUrl: "https://github.com/soil-dev/capsulemcp",
-    icons: ICONS
-  });
+  const tasksCfg = getTasksConfig();
+  const tasksWired = tasksCfg.enabled && !!opts?.clientId;
+  const server2 = new McpServer(
+    {
+      name: "capsulemcp",
+      version: "1.6.0",
+      description: "Read and (optionally) modify Capsule CRM data \u2014 parties, opportunities, projects, tasks, timeline entries, pipelines, tags.",
+      websiteUrl: "https://github.com/soil-dev/capsulemcp",
+      icons: ICONS
+    },
+    tasksWired ? {
+      // tasksWired guards clientId presence; narrow explicitly
+      // for the type-checker rather than using `!`.
+      taskStore: createScopedTaskStore(opts?.clientId ?? ""),
+      capabilities: {
+        tasks: {
+          // The SDK's task capability schema uses {} for "present"
+          // markers, not booleans — see ServerTasksCapabilitySchema
+          // in @modelcontextprotocol/sdk types.ts.
+          list: {},
+          cancel: {},
+          requests: { tools: { call: {} } }
+        }
+      }
+    } : void 0
+  );
+  const registerBatchTool = tasksWired ? registerToolTask : (s, name, description, schema, handler) => registerTool(s, name, description, schema, (input) => handler(input, {}));
   registerTool(
     server2,
     "search_parties",
@@ -1937,14 +2587,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "get_party",
-    "Fetch a single party (person or organisation) by its numeric ID.",
+    "Fetch a single party (person or organisation) by its numeric id. Returns the full record including type, name fields, emails, phones, addresses, websites, and any embedded tags or custom fields. Use embed='tags,fields' to include those in one round-trip. For batch fetches of up to 50 parties at once, use get_parties instead.",
     getPartySchema,
     getParty
   );
   registerTool(
     server2,
     "get_parties",
-    "Batch-fetch up to 10 parties by ID in a single call. Use this when Claude already knows several party IDs to avoid N round trips of get_party.",
+    "Batch-fetch up to 50 parties by ID. For 1\u201310 ids this is a single Capsule round trip (native multi-id endpoint); for 11\u201350 ids the connector transparently splits into 10-id chunks and fans out parallel Capsule requests, so the caller sees a single tool call with all results merged. Use this whenever Claude has several party IDs to avoid N sequential round trips of get_party.",
     getPartiesSchema,
     getParties
   );
@@ -2005,6 +2655,13 @@ function createCapsuleMcpServer() {
       updatePartySchema,
       updateParty
     );
+    registerBatchTool(
+      server2,
+      "batch_update_party",
+      "Update 1\u201350 parties in parallel. Same input shape as update_party but wrapped in an `items` array. Use this \u2014 not N sequential update_party calls \u2014 for any homogeneous multi-record write (mass owner reassignment, bulk metadata corrections, etc.). Capsule has no batch-write API, so the connector fans out parallel HTTP requests with a default concurrency cap of 5 (configurable via CAPSULE_MCP_BATCH_CONCURRENCY). Returns { results: [{ok, ...} per item], summary: {total, succeeded, failed} }. Partial failures are possible \u2014 Capsule has no rollback, so successful items stay applied even if other items 4xx. Read the per-item result array to know which ones need follow-up.",
+      batchUpdatePartySchema,
+      batchUpdateParty
+    );
     registerTool(
       server2,
       "delete_party",
@@ -2086,14 +2743,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "get_opportunity",
-    "Fetch a single opportunity by its numeric id. Returns the full record including value, milestone, owner, party, and any embedded tags/custom fields. Use embed='tags,fields' to include those in one round-trip. For batch fetches of up to 10 opportunities at once, use get_opportunities instead.",
+    "Fetch a single opportunity by its numeric id. Returns the full record including value, milestone, owner, party, and any embedded tags/custom fields. Use embed='tags,fields' to include those in one round-trip. For batch fetches of up to 50 opportunities at once, use get_opportunities instead.",
     getOpportunitySchema,
     getOpportunity
   );
   registerTool(
     server2,
     "get_opportunities",
-    "Batch-fetch up to 10 opportunities by ID in a single call.",
+    "Batch-fetch up to 50 opportunities by id. For 1\u201310 ids this is a single Capsule round trip (native multi-id endpoint); for 11\u201350 ids the connector transparently splits into 10-id chunks and fans out parallel Capsule requests, so the caller sees a single tool call with all results merged. Returns each opportunity's full record (value, milestone, owner, party). For a single id, use get_opportunity instead.",
     getOpportunitiesSchema,
     getOpportunities
   );
@@ -2133,6 +2790,13 @@ function createCapsuleMcpServer() {
       updateOpportunitySchema,
       updateOpportunity
     );
+    registerBatchTool(
+      server2,
+      "batch_update_opportunity",
+      "Update 1\u201350 opportunities in parallel. Same input shape as update_opportunity but wrapped in an `items` array. Use this \u2014 not N sequential update_opportunity calls \u2014 for mass stage transitions (e.g. move a milestone batch to Won), owner reassignments, or value adjustments. Connector fans out parallel HTTP requests, default cap 5 (CAPSULE_MCP_BATCH_CONCURRENCY). Returns { results: [{ok, ...} per item], summary: {total, succeeded, failed} }. Partial failures possible; Capsule has no rollback.",
+      batchUpdateOpportunitySchema,
+      batchUpdateOpportunity
+    );
     registerTool(
       server2,
       "delete_opportunity",
@@ -2158,14 +2822,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "get_project",
-    "Fetch a single project (case) by its numeric ID.",
+    "Fetch a single project (Capsule's term: 'case') by its numeric id. Returns the full record including name, description, status (OPEN/CLOSED), owner, stage, board, opportunityId (if linked), and timestamps. Use embed='tags,fields' to include attached tags and custom field values in one round-trip. For batch fetches of up to 50 projects at once, use get_projects instead. For the project's timeline (notes, captured emails, completed-task records) use list_project_entries.",
     getProjectSchema,
     getProject
   );
   registerTool(
     server2,
     "get_projects",
-    "Batch-fetch up to 10 projects (cases) by ID in a single call.",
+    "Batch-fetch up to 50 projects (cases) by ID. For 1\u201310 ids this is a single Capsule round trip; for 11\u201350 ids the connector transparently splits into 10-id chunks and fans out parallel Capsule requests, so the caller sees a single tool call with all results merged.",
     getProjectsSchema,
     getProjects
   );
@@ -2244,14 +2908,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "get_task",
-    "Fetch a single task by its numeric id. Returns the task's description, due date, owner, completion state, and the entity it's attached to (party / opportunity / project, if any \u2014 standalone tasks not tied to a record are also valid). For batch fetches of up to 10 tasks at once, use get_tasks instead.",
+    "Fetch a single task by its numeric id. Returns the task's description, due date, owner, completion state, and the entity it's attached to (party / opportunity / project, if any \u2014 standalone tasks not tied to a record are also valid). For batch fetches of up to 50 tasks at once, use get_tasks instead.",
     getTaskSchema,
     getTask
   );
   registerTool(
     server2,
     "get_tasks",
-    "Batch-fetch up to 10 tasks by ID in a single call.",
+    "Batch-fetch up to 50 tasks by ID. For 1\u201310 ids this is a single Capsule round trip; for 11\u201350 ids the connector transparently splits into 10-id chunks and fans out parallel Capsule requests, so the caller sees a single tool call with all results merged.",
     getTasksSchema,
     getTasks
   );
@@ -2266,7 +2930,7 @@ function createCapsuleMcpServer() {
     registerTool(
       server2,
       "update_task",
-      "Update fields on an existing task. Only the fields you provide are changed. To mark a task done prefer complete_task.",
+      "Update fields on an existing task: `description`, `dueOn`, `dueTime`, `detail`, `status` (OPEN or COMPLETED), and `ownerId`. Only the fields you provide are changed. To mark a task done, prefer the dedicated `complete_task` tool \u2014 it's idempotent (a no-op success on an already-completed task) and semantically clearer than `update_task status=COMPLETED`. Capsule rejects directly setting status=PENDING (which exists only internally for track-driven tasks); use OPEN or COMPLETED. Completed tasks remain fully editable \u2014 Capsule does not enforce closed-record immutability.",
       updateTaskSchema,
       updateTask
     );
@@ -2277,6 +2941,13 @@ function createCapsuleMcpServer() {
       completeTaskSchema,
       completeTask
     );
+    registerBatchTool(
+      server2,
+      "batch_complete_task",
+      "Mark 1\u201350 tasks COMPLETED in parallel. Pass `ids: [task_id, \u2026]`. Natural for end-of-week catchups, 'close all the follow-ups from this campaign', etc. Connector fans out parallel HTTP requests, default cap 5 (CAPSULE_MCP_BATCH_CONCURRENCY). Returns { results: [{ok, ...} per id], summary: {total, succeeded, failed} }. A task that's already completed or deleted shows up as a per-item failure with the Capsule status; the rest still complete.",
+      batchCompleteTaskSchema,
+      batchCompleteTask
+    );
     registerTool(
       server2,
       "delete_task",
@@ -2288,7 +2959,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "list_party_entries",
-    "List timeline entries (notes, captured emails, completed-task records) for a party. Use this to read the conversation history with a contact or organisation.",
+    "List timeline entries (notes, captured emails, completed-task records) for a party. Returns entries newest-first. Each entry has a type ('note', 'email', 'task'), free-text content, and timestamps. Use this to read the conversation history with a contact or organisation \u2014 answers questions like 'what's the latest with X?' For opportunity or project timelines, use list_opportunity_entries or list_project_entries respectively.",
     listPartyEntriesSchema,
     listPartyEntries
   );
@@ -2309,7 +2980,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "get_entry",
-    "Fetch a single timeline entry by its numeric ID. Returns full content (note body, email subject + body, etc.).",
+    "Fetch a single timeline entry by its numeric id. Returns the full payload \u2014 for a note: the body text; for a captured email: subject, body, from/to, and timestamps; for a completed-task record: the original task fields. Useful when you have an entry id from one of the `list_*_entries` calls and want the full content. To modify the body or activity-type of an existing entry use `update_entry`; to delete one use `delete_entry`.",
     getEntrySchema,
     getEntry
   );
@@ -2324,6 +2995,10 @@ function createCapsuleMcpServer() {
     "get_attachment",
     "Download an attachment by id. Returns image content for image/* types (Claude can describe it natively); decoded text for text/* and application/json (small files); JSON metadata + base64 payload for other binary types (PDF, Office docs, etc.). Files exceeding maxSizeBytes (default 5MB) return metadata only with a `truncated: true` flag.",
     getAttachmentSchema.shape,
+    // get_attachment is read-only — downloads a binary, never mutates.
+    // Mirrors the auto-inferred `readOnlyHint: true` that
+    // `registerTool` applies to every other `get_*` tool.
+    { readOnlyHint: true },
     async (input) => {
       const result = await getAttachment(input);
       if (result.truncated) {
@@ -2451,7 +3126,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "list_stages",
-    "List project stages. Without arguments returns every stage across every board (each carries a .board reference). Pass boardId to scope to one specific board.",
+    "List project (case) stages. Without arguments returns every stage across every board (each entry carries a `.board` reference so you can tell them apart). Pass `boardId` to scope the result to one specific board's stages. Use this to discover the numeric `stage.id` that `create_project` / `update_project` consume \u2014 stage names alone won't do, Capsule resolves by id. For opportunity (deal) stages, use `list_pipelines` instead \u2014 opportunities don't have stages in the project sense.",
     listStagesSchema,
     listStages
   );
@@ -2465,7 +3140,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "list_lostreasons",
-    "List all configured opportunity-loss reasons (e.g. 'Poor Qualification', 'Lost to competitor'). Useful for analysing closed-lost opportunities by reason.",
+    "List all configured opportunity-loss reasons (e.g. 'Poor Qualification', 'Lost to competitor', 'Price too high'). Returns each reason's id and name; the set is account-configured rather than a fixed enum, so call this to discover valid ids before referencing a lostReason in update_opportunity when closing a deal as lost. Useful for analysing closed-lost opportunities by reason.",
     listLostReasonsSchema,
     listLostReasons
   );
@@ -2479,7 +3154,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "list_categories",
-    "List configured entry/task categories (Call, Email, Meeting, Follow-up, etc.) with their colours. Used to label and filter timeline entries and tasks.",
+    "List configured entry/task categories (Call, Email, Meeting, Follow-up, etc.) with their colours. Returns each category's id, name, and colour. The set is account-configured rather than a fixed enum \u2014 call this to discover valid category ids before referencing one in add_note or create_task. Used to label and filter timeline entries and tasks.",
     listCategoriesSchema,
     listCategories
   );
@@ -2554,6 +3229,20 @@ function createCapsuleMcpServer() {
       removeTagByIdSchema,
       removeTagById
     );
+    registerBatchTool(
+      server2,
+      "batch_add_tag",
+      "Attach tags to many entities in parallel \u2014 e.g. tag a list of 20 contacts as 'RSAC26' after a conference, or apply the 'Departed' tag to 10 people in a layoff batch. Pass `items: [{ entity, entityId, tagName }, ...]` (1\u201350 items). Each item is processed identically to a single add_tag call. Connector fans out parallel HTTP requests, default cap 5 (CAPSULE_MCP_BATCH_CONCURRENCY). Returns { results: [{ok, ...} per item], summary: {total, succeeded, failed} }. The list_tags cache is invalidated for each affected entity type.",
+      batchAddTagSchema,
+      batchAddTag
+    );
+    registerBatchTool(
+      server2,
+      "batch_remove_tag_by_id",
+      "Detach tags from many entities in parallel \u2014 cleanup counterpart to batch_add_tag. Pass `items: [{ entity, entityId, tagId }, ...]` (1\u201350 items). Each item is processed identically to a single remove_tag_by_id call (already-detached tags are reported as idempotent successes, not failures). Connector fans out parallel HTTP requests, default cap 5. Returns { results: [{ok, ...} per item], summary: {total, succeeded, failed} }.",
+      batchRemoveTagByIdSchema,
+      batchRemoveTagById
+    );
   }
   registerTool(
     server2,