capsulemcp 1.0.0 → 1.6.0

package/dist/http.js

@@ -1,5 +1,146 @@
 // 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 withRequestContext(initial, fn) {
+  const ctx = {
+    ...initial,
+    tools: [],
+    capsuleCalls: 0,
+    cacheHits: 0,
+    startedAt: Date.now()
+  };
+  return requestContext.run(ctx, async () => {
+    try {
+      return await fn();
+    } finally {
+      logEvent("tool.chain", {
+        ...ctx.clientId ? { clientId: ctx.clientId } : {},
+        tools: ctx.tools,
+        toolCount: ctx.tools.length,
+        capsuleCalls: ctx.capsuleCalls,
+        cacheHits: ctx.cacheHits,
+        durationMs: Date.now() - ctx.startedAt
+      });
+    }
+  });
+}
+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"];
@@ -19,8 +160,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) {
@@ -149,6 +289,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);
@@ -162,10 +304,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);
@@ -205,6 +367,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();
@@ -834,7 +1024,7 @@ function resolveBaseConfig(env = process.env) {
 // src/http/app.ts
 import { createHash as createHash2, timingSafeEqual as timingSafeEqual3 } from "crypto";
 import express from "express";
-import { rateLimit } from "express-rate-limit";
+import { ipKeyGenerator, rateLimit } from "express-rate-limit";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import {
   mcpAuthRouter,
@@ -876,7 +1066,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) }]
@@ -884,10 +1262,93 @@ function wrapAsText(result) {
 }
 function registerTool(server, name, description, schema, handler) {
   const registerWithSchema = server.registerTool.bind(server);
-  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(server, name, description, schema, handler) {
+  const registerWithSchema = server.experimental.tasks.registerToolTask.bind(
+    server.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
@@ -904,6 +1365,98 @@ function confirmFlag() {
   return z2.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);
@@ -979,8 +1532,8 @@ function validateWebsiteAddress(data, ctx) {
     return;
   }
   const parsed = new URL(data.address);
-  const BLOCKED = /* @__PURE__ */ new Set(["javascript:", "data:", "vbscript:"]);
-  if (BLOCKED.has(parsed.protocol)) {
+  const ALLOWED_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
+  if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
     ctx.addIssue({
       code: "custom",
       path: ["address"],
@@ -1042,14 +1595,26 @@ async function getParty(input) {
   return data;
 }
 var getPartiesSchema = z4.object({
-  ids: z4.array(z4.number().int().positive()).min(1).max(10).describe("Array of party IDs (1\u201310). Capsule caps batch fetches at 10."),
+  ids: z4.array(z4.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: z4.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 = z4.object({
   partyId: z4.number().int().positive(),
@@ -1133,6 +1698,14 @@ async function updateParty(input) {
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePut(`/parties/${id}`, { party: body });
 }
+var batchUpdatePartySchema = z4.object({
+  items: z4.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 = z4.object({
   id: z4.number().int().positive(),
   confirm: confirmFlag().describe(
@@ -1335,15 +1908,29 @@ async function getOpportunity(input) {
   return data;
 }
 var getOpportunitiesSchema = z5.object({
-  ids: z5.array(z5.number().int().positive()).min(1).max(10).describe("Array of opportunity IDs (1\u201310). Capsule caps batch fetches at 10."),
+  ids: z5.array(z5.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: z5.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 = z5.object({
   name: z5.string().min(1),
@@ -1404,6 +1991,19 @@ async function updateOpportunity(input) {
     opportunity: body
   });
 }
+var batchUpdateOpportunitySchema = z5.object({
+  items: z5.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 = z5.object({
   id: z5.number().int().positive(),
   confirm: confirmFlag().describe(
@@ -1449,14 +2049,26 @@ async function getProject(input) {
   return data;
 }
 var getProjectsSchema = z6.object({
-  ids: z6.array(z6.number().int().positive()).min(1).max(10).describe("Array of project IDs (1\u201310). Capsule caps batch fetches at 10."),
+  ids: z6.array(z6.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: z6.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 = z6.object({
   name: z6.string().min(1),
@@ -1584,11 +2196,21 @@ async function getTask(input) {
   return data;
 }
 var getTasksSchema = z7.object({
-  ids: z7.array(z7.number().int().positive()).min(1).max(10).describe("Array of task IDs (1\u201310). Capsule caps batch fetches at 10.")
+  ids: z7.array(z7.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 = z7.object({
   description: z7.string().min(1),
@@ -1648,6 +2270,14 @@ async function completeTask(input) {
     task: { status: "COMPLETED" }
   });
 }
+var batchCompleteTaskSchema = z7.object({
+  ids: z7.array(z7.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 = z7.object({
   id: z7.number().int().positive(),
   confirm: confirmFlag().describe(
@@ -1794,7 +2424,7 @@ var paginationFields = {
 };
 var listPipelinesSchema = z9.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
   });
@@ -1805,7 +2435,7 @@ var listMilestonesSchema = z9.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 }
   );
@@ -1820,7 +2450,7 @@ var paginationFields2 = {
 };
 var listBoardsSchema = z10.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
   });
@@ -1834,7 +2464,7 @@ var listStagesSchema = z10.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
   });
@@ -1861,7 +2491,7 @@ var listTagsSchema = z11.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
   });
@@ -1877,9 +2507,11 @@ var addTagSchema = z11.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 = z11.object({
   entity: TagEntity,
@@ -1891,17 +2523,17 @@ var removeTagByIdSchema = z11.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
@@ -1909,6 +2541,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 = z11.object({
+  items: z11.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 = z11.object({
+  items: z11.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
@@ -1918,7 +2568,7 @@ var listUsersSchema = z12.object({
   perPage: z12.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
   });
@@ -1987,7 +2637,7 @@ var paginationFields3 = {
 };
 var listTeamsSchema = z14.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
   });
@@ -1995,7 +2645,7 @@ async function listTeams(input) {
 }
 var listLostReasonsSchema = z14.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
   });
@@ -2003,20 +2653,23 @@ async function listLostReasons(input) {
 }
 var listActivityTypesSchema = z14.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 = z14.object({});
 async function getSite(_input) {
-  const { data } = await capsuleGet("/site");
+  const { data } = await capsuleGetCached("/site");
   return data;
 }
 var listTrackDefinitionsSchema = z14.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 }
   );
@@ -2024,7 +2677,7 @@ async function listTrackDefinitions(input) {
 }
 var listCategoriesSchema = z14.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
   });
@@ -2032,7 +2685,7 @@ async function listCategories(input) {
 }
 var listGoalsSchema = z14.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
   });
@@ -2191,7 +2844,7 @@ var listCustomFieldsSchema = z17.object({
   entity: CustomFieldEntity
 });
 async function listCustomFields(input) {
-  const { data } = await capsuleGet(
+  const { data } = await capsuleGetCached(
     `/${input.entity}/fields/definitions`
   );
   return data;
@@ -2201,7 +2854,7 @@ var getCustomFieldSchema = z17.object({
   fieldId: z17.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;
@@ -2372,7 +3025,7 @@ var listSavedFiltersSchema = z20.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 = z20.object({
@@ -2391,15 +3044,35 @@ async function runSavedFilter(input) {
 }
 
 // src/server.ts
-function createCapsuleMcpServer() {
+function createCapsuleMcpServer(opts) {
   const readOnly = isReadOnly();
-  const server = new McpServer({
-    name: "capsulemcp",
-    version: "1.0.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
-  });
+  const tasksCfg = getTasksConfig();
+  const tasksWired = tasksCfg.enabled && !!opts?.clientId;
+  const server = 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(
     server,
     "search_parties",
@@ -2417,28 +3090,28 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "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(
     server,
     "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
   );
   registerTool(
     server,
     "list_party_opportunities",
-    "List all opportunities linked to a given party.",
+    "List opportunities linked to a given party. Returns the same record shape as get_opportunity, filtered to one party \u2014 use this to answer 'what deals do we have with X?' without enumerating all opportunities. Accepts optional embed (e.g. 'tags,fields') to include those in one round-trip.",
     listPartyOpportunitiesSchema,
     listPartyOpportunities
   );
   registerTool(
     server,
     "list_party_projects",
-    "List all projects (cases) linked to a given party.",
+    "List projects (cases) linked to a given party. Returns the same record shape as get_project, filtered to one party \u2014 use this to answer 'what cases is X involved in?' without enumerating all projects. Accepts optional embed (e.g. 'tags,fields'). For the opportunity-side analogue, use list_party_opportunities.",
     listPartyProjectsSchema,
     listPartyProjects
   );
@@ -2485,6 +3158,13 @@ function createCapsuleMcpServer() {
       updatePartySchema,
       updateParty
     );
+    registerBatchTool(
+      server,
+      "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(
       server,
       "delete_party",
@@ -2566,14 +3246,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "get_opportunity",
-    "Fetch a single opportunity by its numeric ID.",
+    "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(
     server,
     "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
   );
@@ -2594,7 +3274,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "list_associated_projects",
-    "List projects (cases) associated with a given opportunity. The inverse direction (project \u2192 opportunity) is on each project's `opportunity` field directly.",
+    "List projects (cases) associated with a given opportunity. Returns the same record shape as list_projects, filtered to one opportunity. The inverse direction (project \u2192 opportunity) is on each project's `opportunity` field directly, so this tool is only needed for opportunity \u2192 projects discovery \u2014 use list_party_projects for party \u2192 projects.",
     listAssociatedProjectsSchema,
     listAssociatedProjects
   );
@@ -2602,7 +3282,7 @@ function createCapsuleMcpServer() {
     registerTool(
       server,
       "create_opportunity",
-      "Create a new opportunity linked to a party and a pipeline milestone.",
+      "Create a new opportunity linked to a party. Requires partyId and milestoneId (which pins the deal to a specific pipeline stage \u2014 pipeline is inferred from the milestone). Value is optional but if amount is set, currency must be set too (3-letter ISO 4217 code, e.g. 'USD'). Discover valid milestone ids via list_pipelines + list_milestones first. For multi-party deals, use add_additional_party after creation.",
       createOpportunitySchema,
       createOpportunity
     );
@@ -2613,6 +3293,13 @@ function createCapsuleMcpServer() {
       updateOpportunitySchema,
       updateOpportunity
     );
+    registerBatchTool(
+      server,
+      "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(
       server,
       "delete_opportunity",
@@ -2638,14 +3325,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "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(
     server,
     "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
   );
@@ -2660,7 +3347,7 @@ function createCapsuleMcpServer() {
     registerTool(
       server,
       "create_project",
-      "Create a new project (case) in Capsule CRM linked to a party.",
+      "Create a new project (case) in Capsule CRM linked to a party. Requires partyId and name; description, status, owner, and starting board/stage are optional. To pin a project to a specific board+stage on creation, pass stageId (which uniquely identifies a stage within a board). Discover valid ids via list_boards + list_stages. Returns the created project including its assigned id.",
       createProjectSchema,
       createProject
     );
@@ -2724,14 +3411,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "get_task",
-    "Fetch a single task by its numeric ID.",
+    "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(
     server,
     "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
   );
@@ -2746,7 +3433,7 @@ function createCapsuleMcpServer() {
     registerTool(
       server,
       "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
     );
@@ -2757,6 +3444,13 @@ function createCapsuleMcpServer() {
       completeTaskSchema,
       completeTask
     );
+    registerBatchTool(
+      server,
+      "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(
       server,
       "delete_task",
@@ -2768,28 +3462,28 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "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
   );
   registerTool(
     server,
     "list_opportunity_entries",
-    "List timeline entries (notes, captured emails, completed-task records) for an opportunity.",
+    "List timeline entries (notes, captured emails, completed-task records) for an opportunity. Returns entries newest-first. Each entry has a type ('note', 'email', 'task'), free-text content, and timestamps. Use this to answer 'what's the latest on deal X?' For party or project timelines, use list_party_entries or list_project_entries respectively.",
     listOpportunityEntriesSchema,
     listOpportunityEntries
   );
   registerTool(
     server,
     "list_project_entries",
-    "List timeline entries (notes, captured emails, completed-task records) for a project (case).",
+    "List timeline entries (notes, captured emails, completed-task records) for a project (case). Returns entries newest-first. Each entry has a type ('note', 'email', 'task'), free-text content, and timestamps. Use this to answer 'what's the latest on case X?' For party or opportunity timelines, use list_party_entries or list_opportunity_entries respectively.",
     listProjectEntriesSchema,
     listProjectEntries
   );
   registerTool(
     server,
     "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
   );
@@ -2804,6 +3498,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) {
@@ -2910,28 +3608,28 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "list_pipelines",
-    "List all sales pipelines defined in Capsule CRM.",
+    "List all sales pipelines defined in Capsule CRM. Returns each pipeline's id, name, and milestones (deal stages, ordered by position). Use this to discover the pipelineId when creating an opportunity, then pick a milestone from the same pipeline via list_milestones. Pipelines are stable per Capsule account \u2014 list once and cache; they rarely change.",
     listPipelinesSchema,
     listPipelines
   );
   registerTool(
     server,
     "list_milestones",
-    "List all milestones (stages) within a specific opportunity pipeline.",
+    "List milestones (deal stages) within a specific opportunity pipeline. Returns each milestone's id, name, probability, and position. Used when creating opportunities (pass milestoneId to create_opportunity) or moving them across stages (set milestoneId in update_opportunity). Discover the pipelineId first via list_pipelines. Milestones are pipeline-scoped \u2014 not interchangeable across pipelines.",
     listMilestonesSchema,
     listMilestones
   );
   registerTool(
     server,
     "list_boards",
-    "List all project (kase) boards defined in Capsule. A board is a grouping of stages that projects flow through \u2014 the project equivalent of an opportunity pipeline.",
+    "List all project (case) boards defined in Capsule. A board is a grouping of stages that projects flow through \u2014 the project equivalent of an opportunity pipeline. Returns each board's id, name, and stages. Use this to discover boardId when creating a project, then pick a starting stage via list_stages. Like pipelines, boards are stable per account.",
     listBoardsSchema,
     listBoards
   );
   registerTool(
     server,
     "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
   );
@@ -2945,21 +3643,21 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "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
   );
   registerTool(
     server,
     "list_activitytypes",
-    "List all configured activity types (e.g. Call, Meeting, Email). These are the categories used when logging timeline entries.",
+    "List all configured activity types (e.g. Call, Meeting, Email). These are the categories used when logging timeline entries via add_note. Returns each type's id and name. The set is account-configured rather than a fixed enum, so call this to discover valid values before referencing an activityType in entry creation.",
     listActivityTypesSchema,
     listActivityTypes
   );
   registerTool(
     server,
     "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
   );
@@ -3015,7 +3713,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "list_tags",
-    "List all tags available for a given entity type (parties, opportunities, or kases).",
+    "List all tags available for a given entity type (parties, opportunities, or kases). Returns each tag's id, name, and any data-tag field schema. Tags are entity-specific \u2014 a party tag is not interchangeable with an opportunity tag. Use this to discover valid tag ids before calling add_tag, or to display the tag catalogue to the user when they ask 'what tags do we use?'",
     listTagsSchema,
     listTags
   );
@@ -3034,11 +3732,25 @@ function createCapsuleMcpServer() {
       removeTagByIdSchema,
       removeTagById
     );
+    registerBatchTool(
+      server,
+      "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(
+      server,
+      "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(
     server,
     "list_users",
-    "List all users in the Capsule account.",
+    "List all users in the Capsule account. Returns each user's id, username, optional first/last name, role, and party reference. Some users may have null first/last name fields (only username set) \u2014 fall back to username for display. Use this to discover user ids for owner-filtered queries against opportunities, projects, and tasks, or to map a user to their party record via user.party.id.",
     listUsersSchema,
     listUsers
   );
@@ -3059,6 +3771,20 @@ function secretDigest(value) {
 function timingSafeSecretEqual(provided, expected) {
   return timingSafeEqual3(secretDigest(provided), secretDigest(expected));
 }
+var DEFAULT_MCP_RATE_LIMIT_WINDOW_MS = 6e4;
+var DEFAULT_MCP_RATE_LIMIT_MAX = 600;
+var MAX_MEMORY_STORE_WINDOW_MS = 2 ** 31 - 1;
+function resolveMcpRateLimitConfig() {
+  const windowMs = Math.min(
+    readPositiveInt("MCP_HTTP_RATE_LIMIT_WINDOW_MS", DEFAULT_MCP_RATE_LIMIT_WINDOW_MS),
+    MAX_MEMORY_STORE_WINDOW_MS
+  );
+  return {
+    windowMs,
+    limit: readPositiveInt("MCP_HTTP_RATE_LIMIT_MAX", DEFAULT_MCP_RATE_LIMIT_MAX),
+    disabled: process.env["MCP_HTTP_RATE_LIMIT_DISABLED"] === "1"
+  };
+}
 function createApp(opts) {
   const { oauthProvider: oauthProvider2, issuerUrl: issuerUrl2, jsonLimit: jsonLimit2, allowedOrigins } = opts;
   const resourceName = opts.resourceName ?? "Capsule CRM MCP";
@@ -3150,9 +3876,11 @@ function createApp(opts) {
     }
     next();
   };
-  const rateLimitWindowMs = Number(process.env["MCP_HTTP_RATE_LIMIT_WINDOW_MS"]) || 6e4;
-  const rateLimitMax = Number(process.env["MCP_HTTP_RATE_LIMIT_MAX"]) || 600;
-  const rateLimitDisabled = process.env["MCP_HTTP_RATE_LIMIT_DISABLED"] === "1";
+  const {
+    windowMs: rateLimitWindowMs,
+    limit: rateLimitMax,
+    disabled: rateLimitDisabled
+  } = resolveMcpRateLimitConfig();
   const mcpRateLimit = rateLimit({
     windowMs: rateLimitWindowMs,
     limit: rateLimitMax,
@@ -3160,7 +3888,8 @@ function createApp(opts) {
     legacyHeaders: false,
     keyGenerator: (req) => {
       const clientId = req.auth?.clientId;
-      return clientId ?? req.ip ?? "unknown";
+      if (clientId) return clientId;
+      return ipKeyGenerator(req.ip ?? "");
     },
     skip: () => rateLimitDisabled,
     handler: (_req, res) => {
@@ -3198,14 +3927,17 @@ function createApp(opts) {
     express.json({ limit: jsonLimit2 }),
     async (req, res) => {
       try {
-        const server = createCapsuleMcpServer();
+        const clientId = req.auth?.clientId;
+        const server = createCapsuleMcpServer({ clientId });
         const transport = new StreamableHTTPServerTransport({});
         res.on("close", () => {
           void transport.close();
           void server.close();
         });
-        await server.connect(transport);
-        await transport.handleRequest(req, res, req.body);
+        await withRequestContext({ clientId }, async () => {
+          await server.connect(transport);
+          await transport.handleRequest(req, res, req.body);
+        });
       } catch (err) {
         const name = err instanceof Error ? err.name : typeof err;
         const status = err && typeof err === "object" && "status" in err ? Number(err.status) : void 0;