capsulemcp 1.0.1 → 1.6.1

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,9 +304,40 @@ async function doFetch(url, options) {
         "Rate limit exceeded after one retry. Please slow down your requests."
       );
     }
-    return retried;
+    return { ...retried, startedAt, method, url, retriedAfter429: true };
   }
-  return first;
+  return { ...first, startedAt, method, url, retriedAfter429: false };
+}
+async function consumeBody(start, body) {
+  try {
+    return await body();
+  } finally {
+    emitCapsuleRequest(
+      start.method,
+      start.url,
+      start.res,
+      Date.now() - start.startedAt,
+      start.retriedAfter429
+    );
+  }
+}
+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) {
@@ -196,136 +369,173 @@ function buildUrl(path, params) {
 async function capsuleGet(path, params) {
   const token = getToken();
   const url = buildUrl(path, params);
-  const { res, cleanup } = await doFetch(url, { headers: baseHeaders(token) });
+  const start = await doFetch(url, { headers: baseHeaders(token) });
   try {
-    const data = await handleResponse(res);
-    const nextPage = parseNextPage(res.headers.get("Link"));
-    return { data, nextPage };
+    return await consumeBody(start, async () => {
+      const data = await handleResponse(start.res);
+      const nextPage = parseNextPage(start.res.headers.get("Link"));
+      return { data, nextPage };
+    });
   } finally {
-    cleanup();
+    start.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();
   const url = buildUrl(path);
-  const { res, cleanup } = await doFetch(url, {
+  const start = await doFetch(url, {
     method: "POST",
     headers: { ...baseHeaders(token), "Content-Type": "application/json" },
     body: JSON.stringify(body)
   });
   try {
-    return await handleResponse(res);
+    return await consumeBody(start, () => handleResponse(start.res));
   } finally {
-    cleanup();
+    start.cleanup();
   }
 }
 async function capsulePostNoContent(path) {
   if (isReadOnly()) throw new CapsuleReadOnlyError("POST");
   const token = getToken();
   const url = buildUrl(path);
-  const { res, cleanup } = await doFetch(url, {
+  const start = await doFetch(url, {
     method: "POST",
     headers: baseHeaders(token)
   });
   try {
-    if (res.status === 204) return;
-    await throwForStatus(res);
-    await mapAbort(res.text());
+    await consumeBody(start, async () => {
+      if (start.res.status === 204) return;
+      await throwForStatus(start.res);
+      await mapAbort(start.res.text());
+    });
   } finally {
-    cleanup();
+    start.cleanup();
   }
 }
 async function capsuleSearch(path, body, params) {
   const token = getToken();
   const url = buildUrl(path, params);
-  const { res, cleanup } = await doFetch(url, {
+  const start = await doFetch(url, {
     method: "POST",
     headers: { ...baseHeaders(token), "Content-Type": "application/json" },
     body: JSON.stringify(body)
   });
   try {
-    const data = await handleResponse(res);
-    const nextPage = parseNextPage(res.headers.get("Link"));
-    return { data, nextPage };
+    return await consumeBody(start, async () => {
+      const data = await handleResponse(start.res);
+      const nextPage = parseNextPage(start.res.headers.get("Link"));
+      return { data, nextPage };
+    });
   } finally {
-    cleanup();
+    start.cleanup();
   }
 }
 async function capsulePut(path, body) {
   if (isReadOnly()) throw new CapsuleReadOnlyError("PUT");
   const token = getToken();
   const url = buildUrl(path);
-  const { res, cleanup } = await doFetch(url, {
+  const start = await doFetch(url, {
     method: "PUT",
     headers: { ...baseHeaders(token), "Content-Type": "application/json" },
     body: JSON.stringify(body)
   });
   try {
-    return await handleResponse(res);
+    return await consumeBody(start, () => handleResponse(start.res));
   } finally {
-    cleanup();
+    start.cleanup();
   }
 }
 async function capsuleGetBinary(path, maxBytes) {
   const token = getToken();
   const url = buildUrl(path);
-  const { res, cleanup } = await doFetch(url, { headers: baseHeaders(token) });
+  const start = await doFetch(url, { headers: baseHeaders(token) });
   try {
-    await throwForStatus(res);
-    const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
-    const declared = res.headers.get("Content-Length");
-    const declaredBytes = declared ? Number(declared) : NaN;
-    if (maxBytes !== void 0 && Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
-      if (res.body) await res.body.cancel().catch(() => {
-      });
-      return {
-        contentType,
-        buffer: Buffer.alloc(0),
-        truncated: true,
-        sizeBytes: declaredBytes
-      };
-    }
-    if (maxBytes !== void 0 && res.body) {
-      const reader = res.body.getReader();
-      const chunks = [];
-      let total = 0;
-      let truncated = false;
-      while (true) {
-        const { done, value } = await mapAbort(reader.read());
-        if (done) break;
-        total += value.byteLength;
-        if (total > maxBytes) {
-          truncated = true;
-          await reader.cancel().catch(() => {
-          });
-          break;
-        }
-        chunks.push(value);
-      }
-      if (truncated) {
+    return await consumeBody(start, async () => {
+      const res = start.res;
+      await throwForStatus(res);
+      const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
+      const declared = res.headers.get("Content-Length");
+      const declaredBytes = declared ? Number(declared) : NaN;
+      if (maxBytes !== void 0 && Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
+        if (res.body) await res.body.cancel().catch(() => {
+        });
         return {
           contentType,
           buffer: Buffer.alloc(0),
           truncated: true,
-          sizeBytes: total
+          sizeBytes: declaredBytes
         };
       }
-      const buffer2 = Buffer.concat(chunks.map((c) => Buffer.from(c)));
-      return { contentType, buffer: buffer2, sizeBytes: buffer2.length };
-    }
-    const arrayBuffer = await mapAbort(res.arrayBuffer());
-    const buffer = Buffer.from(arrayBuffer);
-    return { contentType, buffer, sizeBytes: buffer.length };
+      if (maxBytes !== void 0 && res.body) {
+        const reader = res.body.getReader();
+        const chunks = [];
+        let total = 0;
+        let truncated = false;
+        while (true) {
+          const { done, value } = await mapAbort(reader.read());
+          if (done) break;
+          total += value.byteLength;
+          if (total > maxBytes) {
+            truncated = true;
+            await reader.cancel().catch(() => {
+            });
+            break;
+          }
+          chunks.push(value);
+        }
+        if (truncated) {
+          return {
+            contentType,
+            buffer: Buffer.alloc(0),
+            truncated: true,
+            sizeBytes: total
+          };
+        }
+        const buffer2 = Buffer.concat(chunks.map((c) => Buffer.from(c)));
+        return { contentType, buffer: buffer2, sizeBytes: buffer2.length };
+      }
+      const arrayBuffer = await mapAbort(res.arrayBuffer());
+      const buffer = Buffer.from(arrayBuffer);
+      return { contentType, buffer, sizeBytes: buffer.length };
+    });
   } finally {
-    cleanup();
+    start.cleanup();
   }
 }
 async function capsulePostBinary(path, body, contentType, filename) {
   if (isReadOnly()) throw new CapsuleReadOnlyError("POST");
   const token = getToken();
   const url = buildUrl(path);
-  const { res, cleanup } = await doFetch(url, {
+  const start = await doFetch(url, {
     method: "POST",
     headers: {
       ...baseHeaders(token),
@@ -336,25 +546,27 @@ async function capsulePostBinary(path, body, contentType, filename) {
     body
   });
   try {
-    return await handleResponse(res);
+    return await consumeBody(start, () => handleResponse(start.res));
   } finally {
-    cleanup();
+    start.cleanup();
   }
 }
 async function capsuleDelete(path) {
   if (isReadOnly()) throw new CapsuleReadOnlyError("DELETE");
   const token = getToken();
   const url = buildUrl(path);
-  const { res, cleanup } = await doFetch(url, {
+  const start = await doFetch(url, {
     method: "DELETE",
     headers: baseHeaders(token)
   });
   try {
-    if (res.status === 204) return;
-    await throwForStatus(res);
-    await mapAbort(res.text());
+    await consumeBody(start, async () => {
+      if (start.res.status === 204) return;
+      await throwForStatus(start.res);
+      await mapAbort(start.res.text());
+    });
   } finally {
-    cleanup();
+    start.cleanup();
   }
 }
 
@@ -834,7 +1046,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 +1088,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 +1284,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 +1387,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);
@@ -1042,14 +1617,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 +1720,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 +1930,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),
@@ -1357,16 +1966,20 @@ var createOpportunitySchema = z5.object({
   probability: z5.number().int().min(0).max(100).optional(),
   ownerId: z5.number().int().positive().optional().describe(
     "Assign to user ID. Defaults to the API-token owner when omitted \u2014 note that opportunities do NOT inherit owner from the linked party, even though one might expect it. Once set, this connector cannot clear the owner back to null (use Capsule's web UI). Discover IDs via list_users."
+  ),
+  teamId: z5.number().int().positive().optional().describe(
+    "Assign to team ID (discover via list_teams). Independent from `ownerId` \u2014 setting one does NOT clear the other on create. Three ownership shapes are valid: owner alone, team alone, or owner+team (the owner must be a member of the team; users can belong to multiple teams \u2014 422 'owner is not a member of the team' otherwise)."
   )
 });
 async function createOpportunity(input) {
-  const { partyId, milestoneId, ownerId, ...rest } = input;
+  const { partyId, milestoneId, ownerId, teamId, ...rest } = input;
   const body = {
     ...rest,
     party: { id: partyId },
     milestone: { id: milestoneId }
   };
   if (ownerId) body["owner"] = { id: ownerId };
+  if (teamId) body["team"] = { id: teamId };
   return capsulePost("/opportunities", { opportunity: body });
 }
 var updateOpportunitySchema = z5.object({
@@ -1385,18 +1998,28 @@ var updateOpportunitySchema = z5.object({
     "Reason the opportunity was lost. Only meaningful when transitioning to a Lost milestone \u2014 Capsule silently drops it for other milestones. Without this set, a connector-driven Lost-close leaves `lostReason: null`. Discover IDs via list_lostreasons."
   ),
   ownerId: z5.number().int().positive().optional().describe(
-    "Reassign owner to user ID. Once set, this connector cannot clear an owner back to null \u2014 use Capsule's web UI for that."
+    "Reassign owner to user ID. Once set, this connector cannot clear an owner back to null \u2014 use Capsule's web UI for that. When you supply `ownerId` and omit `teamId`, the connector fetches the opportunity's current team and includes it in the PUT body to preserve it across the owner change. Without this defensive read, Capsule's PUT would clear the existing team (see NOTES-ON-CAPSULE-API.md \xA727 \u2014 same asymmetric semantic as /kases). Supply `teamId` explicitly on the same call to change the team instead."
+  ),
+  teamId: z5.number().int().positive().nullable().optional().describe(
+    "Reassign team: pass a team ID (discover via list_teams) to set, or `null` to unassign. Capsule preserves the existing owner across a team change (server-side), so `update_opportunity { teamId }` alone is safe \u2014 the owner is carried through. Owner must be a member of the new team or Capsule returns 422 'owner is not a member of the team'. Independent from `ownerId` \u2014 setting `teamId` does NOT clear the owner."
   ),
   fields: z5.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_opportunity"))
 });
 async function updateOpportunity(input) {
-  const { id, milestoneId, ownerId, lostReasonId, fields, ...rest } = input;
+  const { id, milestoneId, ownerId, teamId, lostReasonId, fields, ...rest } = input;
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
   if (milestoneId) body["milestone"] = { id: milestoneId };
+  let resolvedTeamId = teamId;
+  if (ownerId !== void 0 && teamId === void 0) {
+    const { data } = await capsuleGet(`/opportunities/${id}`);
+    resolvedTeamId = data.opportunity?.team?.id ?? void 0;
+  }
   if (ownerId) body["owner"] = { id: ownerId };
+  if (resolvedTeamId === null) body["team"] = null;
+  else if (resolvedTeamId !== void 0) body["team"] = { id: resolvedTeamId };
   if (lostReasonId) body["lostReason"] = { id: lostReasonId };
   const mappedFields = mapFieldsForBody(fields);
   if (mappedFields !== void 0) body["fields"] = mappedFields;
@@ -1404,6 +2027,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 +2085,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 +2232,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 +2306,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 +2460,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 +2471,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 +2486,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 +2500,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 +2527,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 +2543,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 +2559,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 +2577,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 +2604,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 +2673,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 +2681,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 +2689,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 +2713,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 +2721,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 +2880,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 +2890,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 +3061,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 +3080,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.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 server = new McpServer(
+    {
+      name: "capsulemcp",
+      version: "1.6.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
+    },
+    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,14 +3126,14 @@ 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
   );
@@ -2485,6 +3194,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 +3282,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "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(
     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
   );
@@ -2613,6 +3329,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 +3361,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
   );
@@ -2724,14 +3447,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "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(
     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 +3469,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 +3480,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,7 +3498,7 @@ 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
   );
@@ -2789,7 +3519,7 @@ function createCapsuleMcpServer() {
   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 +3534,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) {
@@ -2931,7 +3665,7 @@ function createCapsuleMcpServer() {
   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,7 +3679,7 @@ 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
   );
@@ -2959,7 +3693,7 @@ function createCapsuleMcpServer() {
   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
   );
@@ -3034,6 +3768,20 @@ 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,
@@ -3059,6 +3807,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 +3912,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 +3924,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 +3963,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;