capsulemcp 1.6.5 → 1.8.0

package/README.md

@@ -4,10 +4,10 @@
 
 A [Model Context Protocol](https://modelcontextprotocol.io) server for [Capsule CRM](https://capsulecrm.com). Connect Claude (Desktop, Code, or web Projects via Custom Connector) to your CRM and let it answer natural-language questions across the full record graph: contacts, organisations, opportunities, projects, tasks, and timeline activity. Beyond the basics it covers structured filters with field/operator conditions, saved searches with sort, workflow tracks (templates and instances), file attachments (read + write), audit of deleted records, and batch fetches up to 50 records per call.
 
-- **87 tools** across the Capsule resource graph (49 in read-only mode) — full read coverage plus careful, confirm-gated writes; 6 batched-write tools (`batch_*`) for mass-update workflows
+- **88 tools** across the Capsule resource graph (49 in read-only mode) — full read coverage plus careful, confirm-gated writes; 6 batched-write tools (`batch_*`) for mass-update workflows
 - **Two transports**: stdio for local installs (Claude Desktop / Code), HTTP+OAuth for hosted Custom Connectors
 - **Read-only mode** as a one-env-var flag; works alongside read-scoped Capsule tokens
-- **MCP tool annotations**: 49 read tools carry `readOnlyHint: true`, 7 destructive ones carry `destructiveHint: true` — clients that honor these hints can auto-approve safe reads while still prompting for writes/destructive calls
+- **MCP tool annotations**: 49 read tools carry `readOnlyHint: true`, 8 destructive ones carry `destructiveHint: true` — clients that honor these hints can auto-approve safe reads while still prompting for writes/destructive calls
 - **Apache 2.0**
 
 ## Pick your install
@@ -48,7 +48,7 @@ For most individual users the install is a single JSON snippet pasted into Claud
 
 3. Restart Claude Desktop. The Capsule tools appear in the tool picker.
 
-That's it. The first launch fetches the package from npm (a few seconds); subsequent launches are instant from the npx cache. To pin a specific version, use `"capsulemcp@1.6.5"` in `args`. If you're tracking a fork or an unreleased branch, use the GitHub-ref form instead: `"github:soil-dev/capsulemcp#v1.6.5"` — same arguments, just installs from a git clone rather than the npm registry. See [INSTALL.md](INSTALL.md) for the Claude Code path, manual install, and troubleshooting.
+That's it. The first launch fetches the package from npm (a few seconds); subsequent launches are instant from the npx cache. To pin a specific version, use `"capsulemcp@1.8.0"` in `args`. If you're tracking a fork or an unreleased branch, use the GitHub-ref form instead: `"github:soil-dev/capsulemcp#v1.8.0"` — same arguments, just installs from a git clone rather than the npm registry. See [INSTALL.md](INSTALL.md) for the Claude Code path, manual install, and troubleshooting.
 
 ## Tools
 
@@ -67,7 +67,7 @@ That's it. The first launch fetches the package from npm (a few seconds); subseq
 | Tracks (workflow instances) | `list_track_definitions`, `list_entity_tracks`, `show_track` | `apply_track`, `update_track`, `remove_track` |
 | Saved filters | `list_saved_filters`, `run_saved_filter` | — |
 | Custom fields (schema) | `list_custom_fields`, `get_custom_field` | — |
-| Tags | `list_tags` | `add_tag`, `remove_tag_by_id` |
+| Tags | `list_tags` | `add_tag`, `remove_tag_by_id`, `delete_tag_definition` |
 | Users & teams | `list_users`, `get_current_user`, `list_teams` | — |
 | Reference metadata | `list_lostreasons`, `list_activitytypes`, `list_categories`, `list_goals`, `get_site` | — |
 

package/dist/http.js

@@ -26,6 +26,22 @@ var chainHandlers = {
   "capsule.request": (ctx) => {
     ctx.capsuleCalls += 1;
   },
+  // A timed-out or connection-failed call is still an attempt that
+  // never reaches the `capsule.request` emit (it throws at the fetch
+  // stage). Count it here so `tool.chain.capsuleCalls` stays honest and
+  // a chain whose duration ballooned is explained by a visible failure.
+  "capsule.timeout": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
+  "capsule.error": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
+  // A request that exhausted its 429 retry is a real (doubly-attempted)
+  // outbound call that throws before `capsule.request` fires — count it
+  // so a chain whose latency ballooned on rate-limit backoff is explained.
+  "capsule.ratelimit": (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) => {
@@ -184,6 +200,15 @@ var CapsuleApiError = class extends Error {
   }
   status;
 };
+var CapsuleTimeoutError = class extends CapsuleApiError {
+  constructor() {
+    super(
+      504,
+      `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
+    );
+    this.name = "CapsuleTimeoutError";
+  }
+};
 function getToken() {
   const token = process.env["CAPSULE_API_TOKEN"];
   if (!token) {
@@ -264,30 +289,39 @@ async function mapAbort(p) {
     return await p;
   } catch (err) {
     if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
-      throw new CapsuleApiError(
-        504,
-        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
-      );
+      throw new CapsuleTimeoutError();
     }
     throw err;
   }
 }
 async function fetchWithTimeout(url, options) {
   const { options: opts, cleanup } = withTimeout(options);
+  const startedAt = Date.now();
   try {
     const res = await fetch(url, opts);
     return { res, cleanup };
   } catch (err) {
     cleanup();
-    if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
-      throw new CapsuleApiError(
-        504,
-        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
-      );
+    const isAbort = err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message));
+    emitCapsuleFailure(
+      options?.method ?? "GET",
+      url,
+      Date.now() - startedAt,
+      isAbort ? "timeout" : "network",
+      isAbort ? void 0 : err
+    );
+    if (isAbort) {
+      throw new CapsuleTimeoutError();
     }
     throw err;
   }
 }
+async function drainBody(res) {
+  try {
+    await res.body?.cancel();
+  } catch {
+  }
+}
 async function doFetch(url, options) {
   const startedAt = Date.now();
   const method = options?.method ?? "GET";
@@ -295,10 +329,13 @@ async function doFetch(url, options) {
   if (first.res.status === 429) {
     const delay = parseRateLimitDelay(first.res);
     first.cleanup();
+    await drainBody(first.res);
     await new Promise((resolve) => setTimeout(resolve, delay));
     const retried = await fetchWithTimeout(url, options);
     if (retried.res.status === 429) {
       retried.cleanup();
+      await drainBody(retried.res);
+      emitCapsuleRateLimited(method, url, Date.now() - startedAt);
       throw new CapsuleApiError(
         429,
         "Rate limit exceeded after one retry. Please slow down your requests."
@@ -310,8 +347,7 @@ async function doFetch(url, options) {
 }
 async function consumeBody(start, body) {
   try {
-    return await body();
-  } finally {
+    const result = await body();
     emitCapsuleRequest(
       start.method,
       start.url,
@@ -319,15 +355,31 @@ async function consumeBody(start, body) {
       Date.now() - start.startedAt,
       start.retriedAfter429
     );
+    return result;
+  } catch (err) {
+    if (err instanceof CapsuleTimeoutError) {
+      emitCapsuleFailure(start.method, start.url, Date.now() - start.startedAt, "timeout");
+    } else {
+      emitCapsuleRequest(
+        start.method,
+        start.url,
+        start.res,
+        Date.now() - start.startedAt,
+        start.retriedAfter429
+      );
+    }
+    throw err;
   }
 }
-function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
-  let path = "";
+function redactedPath(url) {
   try {
-    path = redactPath(new URL(url).pathname);
+    return redactPath(new URL(url).pathname);
   } catch {
-    path = "?";
+    return "?";
   }
+}
+function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
+  const path = redactedPath(url);
   const lenHeader = res.headers.get("content-length");
   const responseBytes = lenHeader ? Number.parseInt(lenHeader, 10) : 0;
   logEvent("capsule.request", {
@@ -339,6 +391,37 @@ function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
     ...retriedAfter429 ? { retriedAfter429: true } : {}
   });
 }
+function emitCapsuleFailure(method, url, elapsedMs, reason, err) {
+  const path = redactedPath(url);
+  if (reason === "timeout") {
+    logEvent(
+      "capsule.timeout",
+      { method, path, elapsedMs, timeoutMs: REQUEST_TIMEOUT_MS },
+      { force: true }
+    );
+    return;
+  }
+  const code = extractErrorCode(err);
+  logEvent(
+    "capsule.error",
+    { method, path, elapsedMs, ...code ? { code } : {} },
+    { force: true }
+  );
+}
+function emitCapsuleRateLimited(method, url, elapsedMs) {
+  logEvent(
+    "capsule.ratelimit",
+    { method, path: redactedPath(url), elapsedMs, status: 429 },
+    { force: true }
+  );
+}
+function extractErrorCode(err) {
+  const e = err;
+  const code = e?.cause?.code ?? e?.code;
+  if (typeof code === "string") return code;
+  if (typeof e?.name === "string" && e.name !== "Error") return e.name;
+  return void 0;
+}
 async function throwForStatus(res) {
   if (res.status === 401) {
     const detail = await parseErrorBody(res);
@@ -1142,6 +1225,22 @@ var abortControllers = /* @__PURE__ */ new Map();
 function registerAbortController(taskId, controller) {
   abortControllers.set(taskId, controller);
 }
+var evictionTimers = /* @__PURE__ */ new Map();
+var taskTtls = /* @__PURE__ */ new Map();
+function scheduleEviction(taskId, clientId, ttlMs) {
+  const existing = evictionTimers.get(taskId);
+  if (existing) clearTimeout(existing);
+  taskTtls.set(taskId, ttlMs);
+  const timer = setTimeout(() => {
+    owners.delete(taskId);
+    abortControllers.delete(taskId);
+    evictionTimers.delete(taskId);
+    taskTtls.delete(taskId);
+    logEvent("task.evicted", { taskId, clientId, reason: "ttl" });
+  }, ttlMs);
+  timer.unref?.();
+  evictionTimers.set(taskId, timer);
+}
 function countPerClient(clientId) {
   let n = 0;
   for (const owner of owners.values()) {
@@ -1195,12 +1294,7 @@ function createScopedTaskStore(clientId) {
         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?.();
+      scheduleEviction(task.taskId, clientId, clampedTtl);
       logEvent("task.created", {
         taskId: task.taskId,
         clientId,
@@ -1219,6 +1313,7 @@ function createScopedTaskStore(clientId) {
       }
       logEvent("task.transition", { taskId, clientId, status });
       await global.storeTaskResult(taskId, status, result, sessionId);
+      scheduleEviction(taskId, clientId, taskTtls.get(taskId) ?? getTasksConfig().defaultTtlMs);
     },
     async getTaskResult(taskId, sessionId) {
       if (owners.get(taskId) !== clientId) {
@@ -1238,6 +1333,7 @@ function createScopedTaskStore(clientId) {
       }
       if (status === "completed" || status === "failed" || status === "cancelled") {
         abortControllers.delete(taskId);
+        scheduleEviction(taskId, clientId, taskTtls.get(taskId) ?? getTasksConfig().defaultTtlMs);
       }
     },
     async listTasks(cursor, sessionId) {
@@ -1256,12 +1352,12 @@ function isDestructive(name) {
 }
 function inferAnnotations(name) {
   if (READ_PREFIXES.some((p) => name.startsWith(p))) {
-    return { readOnlyHint: true };
+    return { readOnlyHint: true, destructiveHint: false };
   }
   if (isDestructive(name)) {
-    return { destructiveHint: true };
+    return { readOnlyHint: false, destructiveHint: true };
   }
-  return void 0;
+  return { readOnlyHint: false, destructiveHint: false };
 }
 function argFieldNames(input) {
   if (input === null || typeof input !== "object" || Array.isArray(input)) return [];
@@ -1565,6 +1661,26 @@ async function readEntityRefs(path, responseKey) {
   };
 }
 
+// src/capsule/multi-get.ts
+var MULTI_GET_MAX_IDS = 10;
+async function chunkedMultiGet(base, responseKey, ids, params) {
+  if (ids.length <= MULTI_GET_MAX_IDS) {
+    const { data } = await capsuleGet(
+      `${base}/${ids.join(",")}`,
+      params
+    );
+    return data;
+  }
+  const chunks = chunk(ids, MULTI_GET_MAX_IDS);
+  const responses = await Promise.all(
+    chunks.map(
+      (chunkIds) => capsuleGet(`${base}/${chunkIds.join(",")}`, params)
+    )
+  );
+  const merged = responses.flatMap((r) => r.data[responseKey] ?? []);
+  return { ...responses[0]?.data ?? {}, [responseKey]: merged };
+}
+
 // src/tools/custom-field-helpers.ts
 import { z as z6 } from "zod";
 var CustomFieldWriteSchema = z6.object({
@@ -1687,20 +1803,7 @@ var getPartiesSchema = z7.object({
   embed: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getParties(input) {
-  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) };
+  return chunkedMultiGet("/parties", "parties", input.ids, { embed: input.embed });
 }
 var listPartyOpportunitiesSchema = z7.object({
   partyId: positiveId,
@@ -2011,23 +2114,7 @@ var getOpportunitiesSchema = z8.object({
   embed: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getOpportunities(input) {
-  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 { opportunities: responses.flatMap((r) => r.data.opportunities) };
+  return chunkedMultiGet("/opportunities", "opportunities", input.ids, { embed: input.embed });
 }
 var createOpportunitySchema = z8.object({
   name: z8.string().min(1),
@@ -2155,20 +2242,7 @@ var getProjectsSchema = z9.object({
   embed: z9.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getProjects(input) {
-  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) };
+  return chunkedMultiGet("/kases", "kases", input.ids, { embed: input.embed });
 }
 var createProjectSchema = z9.object({
   name: z9.string().min(1),
@@ -2300,16 +2374,7 @@ var getTasksSchema = z10.object({
   )
 });
 async function getTasks(input) {
-  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) };
+  return chunkedMultiGet("/tasks", "tasks", input.ids);
 }
 var createTaskSchema = z10.object({
   description: z10.string().min(1),
@@ -2410,14 +2475,102 @@ var listEntriesPagination = {
 };
 var listPartyEntriesSchema = z11.object({
   partyId: positiveId,
-  ...listEntriesPagination
+  ...listEntriesPagination,
+  includeLinkedPersons: z11.boolean().optional().describe(
+    "When true AND `partyId` is an ORGANISATION, also include entries filed against the organisation's linked people (the persons whose `organisation` field references this org). The connector enumerates linked persons via `GET /parties/{orgId}/people`, fans out `GET /parties/{personId}/entries` in parallel (concurrency-capped, default 5 / configurable via `CAPSULE_MCP_BATCH_CONCURRENCY`), and merges into a single feed sorted by `entryAt` descending, deduped by entry id. Default is `false` \u2014 single GET, existing behaviour unchanged. WHY THIS FLAG EXISTS: Capsule's API files each entry against exactly one party row (verified v1.6.6 wire-trace probe 4 \u2014 POST /entries rejects multi-party bodies with 422 'entry must be linked to either a party, opportunity or kase'). For an organisation with multiple contacts, captured emails almost always land on a person row, not the org. As a result, `list_party_entries(orgId)` with `includeLinkedPersons: false` will miss recent customer-facing email \u2014 even though the org's own `lastContactedAt` is updated by the activity. This flag is the correct call for any 'what's new with $ORG?' question. WHEN `partyId` IS A PERSON: silently no-op \u2014 persons have no linked-people relationship in Capsule's data model, so the flag is functionally inert (the connector still issues a cheap `/people` check; the response is empty). LATENCY: 1 + N round trips for an org with N linked people, concurrency-capped (typical: 2-3 waves for N=10). Linked-person enumeration reads the first 100 linked people; use list_employees for explicit pagination when an organisation has more contacts than that. Use `includeLinkedPersons: false` for fast pre-screen reads where you only need the org-row entries (e.g. invoice/contract notes that are typically filed at the org level). PAGINATION CAVEAT: `page` and `perPage` apply to the MERGED window, and the merge has a hard ceiling \u2014 it reliably orders only the most-recent ~100 entries across the org + its people (each party is fetched at Capsule's per-party cap of 100, and a top-100-per-party merge is correct only up to global position 100). Windows that cross the ceiling are truncated to the entries still inside that top-100 set; windows starting beyond it return no entries and end the feed. It does NOT continue into older history. To read a specific contact's full timeline beyond the merged ceiling, call `list_party_entries` on that person's id directly (the default single-GET path paginates natively with no ceiling). For the LLM-driven 'what's the latest with $ORG' query this is the typical use of, the first page is exact and the ceiling is never reached."
+  )
 });
+async function fanOutPartyEntries(partyIds, embed, perPage) {
+  const concurrency = getBatchConcurrency();
+  const results = new Array(partyIds.length);
+  let cursor = 0;
+  async function worker() {
+    while (true) {
+      const i = cursor;
+      cursor += 1;
+      if (i >= partyIds.length) return;
+      const id = partyIds[i];
+      const { data, nextPage } = await capsuleGet(
+        `/parties/${id}/entries`,
+        {
+          embed,
+          page: 1,
+          perPage
+        }
+      );
+      results[i] = { entries: data.entries, nextPage };
+    }
+  }
+  const workers = [];
+  for (let w = 0; w < Math.min(concurrency, partyIds.length); w++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return results;
+}
+function mergedTimelineCandidatePerParty(page, perPage) {
+  return Math.min(page * perPage, 100);
+}
+function mergedTimelineNextPage(page, perPage, mergedLength, upstreamHasNextPage) {
+  const requestedWindowEnd = page * perPage;
+  if (mergedLength > requestedWindowEnd) return page + 1;
+  const nextWindowWithinCap = requestedWindowEnd < 100;
+  if (nextWindowWithinCap && upstreamHasNextPage) return page + 1;
+  return void 0;
+}
 async function listPartyEntries(input) {
-  const { data, nextPage } = await capsuleGet(
-    `/parties/${input.partyId}/entries`,
-    { embed: input.embed, page: input.page, perPage: input.perPage }
+  const { partyId, embed, page, perPage, includeLinkedPersons } = input;
+  if (!includeLinkedPersons) {
+    const { data, nextPage: nextPage2 } = await capsuleGet(
+      `/parties/${partyId}/entries`,
+      { embed, page, perPage }
+    );
+    return { ...data, nextPage: nextPage2 };
+  }
+  const { data: peopleData } = await capsuleGet(
+    `/parties/${partyId}/people`,
+    { page: 1, perPage: 100 }
   );
-  return { ...data, nextPage };
+  const peopleIds = (peopleData.parties ?? []).map((p) => p.id);
+  if (peopleIds.length === 0) {
+    const { data, nextPage: nextPage2 } = await capsuleGet(
+      `/parties/${partyId}/entries`,
+      { embed, page, perPage }
+    );
+    return { ...data, nextPage: nextPage2 };
+  }
+  const targetIds = [partyId, ...peopleIds];
+  const perPartyPages = await fanOutPartyEntries(
+    targetIds,
+    embed,
+    mergedTimelineCandidatePerParty(page, perPage)
+  );
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const { entries } of perPartyPages) {
+    for (const raw of entries) {
+      const e = raw;
+      if (typeof e?.id !== "number") continue;
+      if (seen.has(e.id)) continue;
+      seen.add(e.id);
+      merged.push(e);
+    }
+  }
+  merged.sort((a, b) => {
+    const ax = a.entryAt ?? "";
+    const bx = b.entryAt ?? "";
+    if (ax !== bx) return bx.localeCompare(ax);
+    return b.id - a.id;
+  });
+  const start = (page - 1) * perPage;
+  const slice = merged.slice(start, start + perPage);
+  const nextPage = mergedTimelineNextPage(
+    page,
+    perPage,
+    merged.length,
+    perPartyPages.some((p) => p.nextPage !== void 0)
+  );
+  return { entries: slice, ...nextPage !== void 0 ? { nextPage } : {} };
 }
 var listOpportunityEntriesSchema = z11.object({
   opportunityId: positiveId,
@@ -2640,6 +2793,28 @@ async function removeTagById(input) {
   invalidateByPrefix(TAG_LIST_PATH[entity], "remove_tag_by_id");
   return result;
 }
+var deleteTagDefinitionSchema = z14.object({
+  entity: TagEntity,
+  tagId: positiveId.describe(
+    "The tag definition's id (from list_tags, or embed='tags' on a record). NOT an entity id."
+  ),
+  confirm: confirmFlag().describe(
+    "Must be set to true. DESTRUCTIVE & tenant-wide: permanently deletes the tag DEFINITION from this entity type's tag namespace, removing it from EVERY record that shares it \u2014 not just one. To detach a tag from a single record while keeping the definition, use remove_tag_by_id instead. Irreversible (the definition is gone; re-creating by name via add_tag mints a new id). Idempotent on retry."
+  )
+});
+async function deleteTagDefinition(input) {
+  const { entity, tagId, confirm } = input;
+  if (confirm !== true) {
+    throw new Error("delete_tag_definition requires confirm: true");
+  }
+  const result = await idempotent(
+    () => capsuleDelete(`/${entity}/tags/${tagId}`),
+    () => ({ deleted: true, alreadyDeleted: false, entity, tagId }),
+    () => ({ deleted: true, alreadyDeleted: true, entity, tagId })
+  );
+  invalidateByPrefix(TAG_LIST_PATH[entity], "delete_tag_definition");
+  return result;
+}
 var { schema: batchAddTagSchema, handler: batchAddTag } = defineBatch({
   toolName: "batch_add_tag",
   itemSchema: addTagSchema,
@@ -3145,7 +3320,7 @@ function createCapsuleMcpServer(opts) {
   const server = new McpServer(
     {
       name: "capsulemcp",
-      version: "1.6.5",
+      version: "1.8.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
@@ -3563,7 +3738,7 @@ function createCapsuleMcpServer(opts) {
   registerTool(
     server,
     "list_party_entries",
-    "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.",
+    "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. IMPORTANT for organisations: pass `includeLinkedPersons: true` to surface entries filed against the org's linked people (sales-conversation emails almost always land on a person row, not the org row \u2014 Capsule's API files each entry against exactly one party). Without this flag, an org with active customer-facing email will appear quiet here even though its `lastContactedAt` is current. For any 'what's new with $ORG?' query, set `includeLinkedPersons: true`.",
     listPartyEntriesSchema,
     listPartyEntries
   );
@@ -3600,9 +3775,12 @@ function createCapsuleMcpServer(opts) {
     "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 },
+    // Mirrors the auto-inferred `{readOnlyHint: true, destructiveHint:
+    // false}` that `registerTool` applies to every other `get_*` tool.
+    // Explicit destructiveHint: false is load-bearing — MCP spec
+    // defaults destructiveHint to `true`, so omitting it would (in
+    // some client implementations) classify this read as destructive.
+    { readOnlyHint: true, destructiveHint: false },
     async (input) => {
       const result = await getAttachment(input);
       if (result.truncated) {
@@ -3833,6 +4011,13 @@ function createCapsuleMcpServer(opts) {
       removeTagByIdSchema,
       removeTagById
     );
+    registerTool(
+      server,
+      "delete_tag_definition",
+      "DESTRUCTIVE & TENANT-WIDE: permanently delete a tag DEFINITION from an entity type's tag namespace (parties / opportunities / kases). Unlike remove_tag_by_id \u2014 which detaches a tag from ONE record and leaves the definition intact for others \u2014 this removes the definition itself, so the tag disappears from EVERY record that shared it. Use it to clean up stray / mistyped / test tag definitions polluting the tenant-global list. Requires confirm=true. Always read the affected tag first via list_tags and confirm with the user; if you only want to untag one record, use remove_tag_by_id instead. Irreversible (re-creating by name via add_tag mints a brand-new id). Idempotent on retry: `{deleted: true, alreadyDeleted: false, entity, tagId}` on a fresh delete, or `{deleted: true, alreadyDeleted: true, entity, tagId}` if the definition was already gone (Capsule's 404 is caught). Endpoint verified empirically (DELETE /<entity>/tags/{id} \u2192 204).",
+      deleteTagDefinitionSchema,
+      deleteTagDefinition
+    );
     registerBatchTool(
       server,
       "batch_add_tag",
@@ -3950,6 +4135,34 @@ function createApp(opts) {
   };
   app2.get("/icon.svg", iconHandler);
   app2.get("/favicon.ico", iconHandler);
+  const LANDING_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>capsulemcp</title>
+<link rel="icon" type="image/svg+xml" href="/icon.svg">
+<link rel="apple-touch-icon" href="/icon.svg">
+<meta name="description" content="Model Context Protocol server for Capsule CRM. MCP endpoint: /mcp">
+<style>
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;max-width:42em;margin:3em auto;padding:0 1em;color:#222;line-height:1.5}
+h1{font-size:1.6em;margin-bottom:0.2em}
+code{background:#f3f3f3;padding:0.1em 0.35em;border-radius:3px;font-size:0.95em}
+a{color:#1e3a8a}
+.muted{color:#666;font-size:0.92em}
+</style>
+</head>
+<body>
+<h1>capsulemcp</h1>
+<p>This is the HTTP+OAuth deployment of <a href="https://github.com/soil-dev/capsulemcp">capsulemcp</a>, a Model Context Protocol (MCP) server for Capsule CRM.</p>
+<p>The MCP endpoint is at <code>/mcp</code>. Use Claude.ai's Custom Connector flow (or any MCP-compatible client) to connect &mdash; this URL is not navigable by hand.</p>
+<p class="muted">Source: <a href="https://github.com/soil-dev/capsulemcp">github.com/soil-dev/capsulemcp</a> &middot; License: Apache-2.0</p>
+</body>
+</html>
+`;
+  app2.get("/", (_req, res) => {
+    res.set("Content-Type", "text/html; charset=utf-8").set("Cache-Control", "public, max-age=3600").send(LANDING_HTML);
+  });
   const guardOrigin = (req, res, next) => {
     const origin = req.get("Origin");
     if (!origin) {

package/dist/index.js

@@ -31,6 +31,22 @@ var chainHandlers = {
   "capsule.request": (ctx) => {
     ctx.capsuleCalls += 1;
   },
+  // A timed-out or connection-failed call is still an attempt that
+  // never reaches the `capsule.request` emit (it throws at the fetch
+  // stage). Count it here so `tool.chain.capsuleCalls` stays honest and
+  // a chain whose duration ballooned is explained by a visible failure.
+  "capsule.timeout": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
+  "capsule.error": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
+  // A request that exhausted its 429 retry is a real (doubly-attempted)
+  // outbound call that throws before `capsule.request` fires — count it
+  // so a chain whose latency ballooned on rate-limit backoff is explained.
+  "capsule.ratelimit": (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) => {
@@ -166,6 +182,15 @@ var CapsuleApiError = class extends Error {
   }
   status;
 };
+var CapsuleTimeoutError = class extends CapsuleApiError {
+  constructor() {
+    super(
+      504,
+      `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
+    );
+    this.name = "CapsuleTimeoutError";
+  }
+};
 function getToken() {
   const token = process.env["CAPSULE_API_TOKEN"];
   if (!token) {
@@ -246,30 +271,39 @@ async function mapAbort(p) {
     return await p;
   } catch (err) {
     if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
-      throw new CapsuleApiError(
-        504,
-        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
-      );
+      throw new CapsuleTimeoutError();
     }
     throw err;
   }
 }
 async function fetchWithTimeout(url, options) {
   const { options: opts, cleanup } = withTimeout(options);
+  const startedAt = Date.now();
   try {
     const res = await fetch(url, opts);
     return { res, cleanup };
   } catch (err) {
     cleanup();
-    if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
-      throw new CapsuleApiError(
-        504,
-        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
-      );
+    const isAbort = err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message));
+    emitCapsuleFailure(
+      options?.method ?? "GET",
+      url,
+      Date.now() - startedAt,
+      isAbort ? "timeout" : "network",
+      isAbort ? void 0 : err
+    );
+    if (isAbort) {
+      throw new CapsuleTimeoutError();
     }
     throw err;
   }
 }
+async function drainBody(res) {
+  try {
+    await res.body?.cancel();
+  } catch {
+  }
+}
 async function doFetch(url, options) {
   const startedAt = Date.now();
   const method = options?.method ?? "GET";
@@ -277,10 +311,13 @@ async function doFetch(url, options) {
   if (first.res.status === 429) {
     const delay = parseRateLimitDelay(first.res);
     first.cleanup();
+    await drainBody(first.res);
     await new Promise((resolve) => setTimeout(resolve, delay));
     const retried = await fetchWithTimeout(url, options);
     if (retried.res.status === 429) {
       retried.cleanup();
+      await drainBody(retried.res);
+      emitCapsuleRateLimited(method, url, Date.now() - startedAt);
       throw new CapsuleApiError(
         429,
         "Rate limit exceeded after one retry. Please slow down your requests."
@@ -292,8 +329,7 @@ async function doFetch(url, options) {
 }
 async function consumeBody(start, body) {
   try {
-    return await body();
-  } finally {
+    const result = await body();
     emitCapsuleRequest(
       start.method,
       start.url,
@@ -301,15 +337,31 @@ async function consumeBody(start, body) {
       Date.now() - start.startedAt,
       start.retriedAfter429
     );
+    return result;
+  } catch (err) {
+    if (err instanceof CapsuleTimeoutError) {
+      emitCapsuleFailure(start.method, start.url, Date.now() - start.startedAt, "timeout");
+    } else {
+      emitCapsuleRequest(
+        start.method,
+        start.url,
+        start.res,
+        Date.now() - start.startedAt,
+        start.retriedAfter429
+      );
+    }
+    throw err;
   }
 }
-function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
-  let path = "";
+function redactedPath(url) {
   try {
-    path = redactPath(new URL(url).pathname);
+    return redactPath(new URL(url).pathname);
   } catch {
-    path = "?";
+    return "?";
   }
+}
+function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
+  const path = redactedPath(url);
   const lenHeader = res.headers.get("content-length");
   const responseBytes = lenHeader ? Number.parseInt(lenHeader, 10) : 0;
   logEvent("capsule.request", {
@@ -321,6 +373,37 @@ function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
     ...retriedAfter429 ? { retriedAfter429: true } : {}
   });
 }
+function emitCapsuleFailure(method, url, elapsedMs, reason, err) {
+  const path = redactedPath(url);
+  if (reason === "timeout") {
+    logEvent(
+      "capsule.timeout",
+      { method, path, elapsedMs, timeoutMs: REQUEST_TIMEOUT_MS },
+      { force: true }
+    );
+    return;
+  }
+  const code = extractErrorCode(err);
+  logEvent(
+    "capsule.error",
+    { method, path, elapsedMs, ...code ? { code } : {} },
+    { force: true }
+  );
+}
+function emitCapsuleRateLimited(method, url, elapsedMs) {
+  logEvent(
+    "capsule.ratelimit",
+    { method, path: redactedPath(url), elapsedMs, status: 429 },
+    { force: true }
+  );
+}
+function extractErrorCode(err) {
+  const e = err;
+  const code = e?.cause?.code ?? e?.code;
+  if (typeof code === "string") return code;
+  if (typeof e?.name === "string" && e.name !== "Error") return e.name;
+  return void 0;
+}
 async function throwForStatus(res) {
   if (res.status === 401) {
     const detail = await parseErrorBody(res);
@@ -639,6 +722,22 @@ var abortControllers = /* @__PURE__ */ new Map();
 function registerAbortController(taskId, controller) {
   abortControllers.set(taskId, controller);
 }
+var evictionTimers = /* @__PURE__ */ new Map();
+var taskTtls = /* @__PURE__ */ new Map();
+function scheduleEviction(taskId, clientId, ttlMs) {
+  const existing = evictionTimers.get(taskId);
+  if (existing) clearTimeout(existing);
+  taskTtls.set(taskId, ttlMs);
+  const timer = setTimeout(() => {
+    owners.delete(taskId);
+    abortControllers.delete(taskId);
+    evictionTimers.delete(taskId);
+    taskTtls.delete(taskId);
+    logEvent("task.evicted", { taskId, clientId, reason: "ttl" });
+  }, ttlMs);
+  timer.unref?.();
+  evictionTimers.set(taskId, timer);
+}
 function countPerClient(clientId) {
   let n = 0;
   for (const owner of owners.values()) {
@@ -692,12 +791,7 @@ function createScopedTaskStore(clientId) {
         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?.();
+      scheduleEviction(task.taskId, clientId, clampedTtl);
       logEvent("task.created", {
         taskId: task.taskId,
         clientId,
@@ -716,6 +810,7 @@ function createScopedTaskStore(clientId) {
       }
       logEvent("task.transition", { taskId, clientId, status });
       await global.storeTaskResult(taskId, status, result, sessionId);
+      scheduleEviction(taskId, clientId, taskTtls.get(taskId) ?? getTasksConfig().defaultTtlMs);
     },
     async getTaskResult(taskId, sessionId) {
       if (owners.get(taskId) !== clientId) {
@@ -735,6 +830,7 @@ function createScopedTaskStore(clientId) {
       }
       if (status === "completed" || status === "failed" || status === "cancelled") {
         abortControllers.delete(taskId);
+        scheduleEviction(taskId, clientId, taskTtls.get(taskId) ?? getTasksConfig().defaultTtlMs);
       }
     },
     async listTasks(cursor, sessionId) {
@@ -753,12 +849,12 @@ function isDestructive(name) {
 }
 function inferAnnotations(name) {
   if (READ_PREFIXES.some((p) => name.startsWith(p))) {
-    return { readOnlyHint: true };
+    return { readOnlyHint: true, destructiveHint: false };
   }
   if (isDestructive(name)) {
-    return { destructiveHint: true };
+    return { readOnlyHint: false, destructiveHint: true };
   }
-  return void 0;
+  return { readOnlyHint: false, destructiveHint: false };
 }
 function argFieldNames(input) {
   if (input === null || typeof input !== "object" || Array.isArray(input)) return [];
@@ -1062,6 +1158,26 @@ async function readEntityRefs(path, responseKey) {
   };
 }
 
+// src/capsule/multi-get.ts
+var MULTI_GET_MAX_IDS = 10;
+async function chunkedMultiGet(base, responseKey, ids, params) {
+  if (ids.length <= MULTI_GET_MAX_IDS) {
+    const { data } = await capsuleGet(
+      `${base}/${ids.join(",")}`,
+      params
+    );
+    return data;
+  }
+  const chunks = chunk(ids, MULTI_GET_MAX_IDS);
+  const responses = await Promise.all(
+    chunks.map(
+      (chunkIds) => capsuleGet(`${base}/${chunkIds.join(",")}`, params)
+    )
+  );
+  const merged = responses.flatMap((r) => r.data[responseKey] ?? []);
+  return { ...responses[0]?.data ?? {}, [responseKey]: merged };
+}
+
 // src/tools/custom-field-helpers.ts
 import { z as z5 } from "zod";
 var CustomFieldWriteSchema = z5.object({
@@ -1184,20 +1300,7 @@ var getPartiesSchema = z6.object({
   embed: z6.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getParties(input) {
-  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) };
+  return chunkedMultiGet("/parties", "parties", input.ids, { embed: input.embed });
 }
 var listPartyOpportunitiesSchema = z6.object({
   partyId: positiveId,
@@ -1508,23 +1611,7 @@ var getOpportunitiesSchema = z7.object({
   embed: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getOpportunities(input) {
-  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 { opportunities: responses.flatMap((r) => r.data.opportunities) };
+  return chunkedMultiGet("/opportunities", "opportunities", input.ids, { embed: input.embed });
 }
 var createOpportunitySchema = z7.object({
   name: z7.string().min(1),
@@ -1652,20 +1739,7 @@ var getProjectsSchema = z8.object({
   embed: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getProjects(input) {
-  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) };
+  return chunkedMultiGet("/kases", "kases", input.ids, { embed: input.embed });
 }
 var createProjectSchema = z8.object({
   name: z8.string().min(1),
@@ -1797,16 +1871,7 @@ var getTasksSchema = z9.object({
   )
 });
 async function getTasks(input) {
-  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) };
+  return chunkedMultiGet("/tasks", "tasks", input.ids);
 }
 var createTaskSchema = z9.object({
   description: z9.string().min(1),
@@ -1907,14 +1972,102 @@ var listEntriesPagination = {
 };
 var listPartyEntriesSchema = z10.object({
   partyId: positiveId,
-  ...listEntriesPagination
+  ...listEntriesPagination,
+  includeLinkedPersons: z10.boolean().optional().describe(
+    "When true AND `partyId` is an ORGANISATION, also include entries filed against the organisation's linked people (the persons whose `organisation` field references this org). The connector enumerates linked persons via `GET /parties/{orgId}/people`, fans out `GET /parties/{personId}/entries` in parallel (concurrency-capped, default 5 / configurable via `CAPSULE_MCP_BATCH_CONCURRENCY`), and merges into a single feed sorted by `entryAt` descending, deduped by entry id. Default is `false` \u2014 single GET, existing behaviour unchanged. WHY THIS FLAG EXISTS: Capsule's API files each entry against exactly one party row (verified v1.6.6 wire-trace probe 4 \u2014 POST /entries rejects multi-party bodies with 422 'entry must be linked to either a party, opportunity or kase'). For an organisation with multiple contacts, captured emails almost always land on a person row, not the org. As a result, `list_party_entries(orgId)` with `includeLinkedPersons: false` will miss recent customer-facing email \u2014 even though the org's own `lastContactedAt` is updated by the activity. This flag is the correct call for any 'what's new with $ORG?' question. WHEN `partyId` IS A PERSON: silently no-op \u2014 persons have no linked-people relationship in Capsule's data model, so the flag is functionally inert (the connector still issues a cheap `/people` check; the response is empty). LATENCY: 1 + N round trips for an org with N linked people, concurrency-capped (typical: 2-3 waves for N=10). Linked-person enumeration reads the first 100 linked people; use list_employees for explicit pagination when an organisation has more contacts than that. Use `includeLinkedPersons: false` for fast pre-screen reads where you only need the org-row entries (e.g. invoice/contract notes that are typically filed at the org level). PAGINATION CAVEAT: `page` and `perPage` apply to the MERGED window, and the merge has a hard ceiling \u2014 it reliably orders only the most-recent ~100 entries across the org + its people (each party is fetched at Capsule's per-party cap of 100, and a top-100-per-party merge is correct only up to global position 100). Windows that cross the ceiling are truncated to the entries still inside that top-100 set; windows starting beyond it return no entries and end the feed. It does NOT continue into older history. To read a specific contact's full timeline beyond the merged ceiling, call `list_party_entries` on that person's id directly (the default single-GET path paginates natively with no ceiling). For the LLM-driven 'what's the latest with $ORG' query this is the typical use of, the first page is exact and the ceiling is never reached."
+  )
 });
+async function fanOutPartyEntries(partyIds, embed, perPage) {
+  const concurrency = getBatchConcurrency();
+  const results = new Array(partyIds.length);
+  let cursor = 0;
+  async function worker() {
+    while (true) {
+      const i = cursor;
+      cursor += 1;
+      if (i >= partyIds.length) return;
+      const id = partyIds[i];
+      const { data, nextPage } = await capsuleGet(
+        `/parties/${id}/entries`,
+        {
+          embed,
+          page: 1,
+          perPage
+        }
+      );
+      results[i] = { entries: data.entries, nextPage };
+    }
+  }
+  const workers = [];
+  for (let w = 0; w < Math.min(concurrency, partyIds.length); w++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return results;
+}
+function mergedTimelineCandidatePerParty(page, perPage) {
+  return Math.min(page * perPage, 100);
+}
+function mergedTimelineNextPage(page, perPage, mergedLength, upstreamHasNextPage) {
+  const requestedWindowEnd = page * perPage;
+  if (mergedLength > requestedWindowEnd) return page + 1;
+  const nextWindowWithinCap = requestedWindowEnd < 100;
+  if (nextWindowWithinCap && upstreamHasNextPage) return page + 1;
+  return void 0;
+}
 async function listPartyEntries(input) {
-  const { data, nextPage } = await capsuleGet(
-    `/parties/${input.partyId}/entries`,
-    { embed: input.embed, page: input.page, perPage: input.perPage }
+  const { partyId, embed, page, perPage, includeLinkedPersons } = input;
+  if (!includeLinkedPersons) {
+    const { data, nextPage: nextPage2 } = await capsuleGet(
+      `/parties/${partyId}/entries`,
+      { embed, page, perPage }
+    );
+    return { ...data, nextPage: nextPage2 };
+  }
+  const { data: peopleData } = await capsuleGet(
+    `/parties/${partyId}/people`,
+    { page: 1, perPage: 100 }
   );
-  return { ...data, nextPage };
+  const peopleIds = (peopleData.parties ?? []).map((p) => p.id);
+  if (peopleIds.length === 0) {
+    const { data, nextPage: nextPage2 } = await capsuleGet(
+      `/parties/${partyId}/entries`,
+      { embed, page, perPage }
+    );
+    return { ...data, nextPage: nextPage2 };
+  }
+  const targetIds = [partyId, ...peopleIds];
+  const perPartyPages = await fanOutPartyEntries(
+    targetIds,
+    embed,
+    mergedTimelineCandidatePerParty(page, perPage)
+  );
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const { entries } of perPartyPages) {
+    for (const raw of entries) {
+      const e = raw;
+      if (typeof e?.id !== "number") continue;
+      if (seen.has(e.id)) continue;
+      seen.add(e.id);
+      merged.push(e);
+    }
+  }
+  merged.sort((a, b) => {
+    const ax = a.entryAt ?? "";
+    const bx = b.entryAt ?? "";
+    if (ax !== bx) return bx.localeCompare(ax);
+    return b.id - a.id;
+  });
+  const start = (page - 1) * perPage;
+  const slice = merged.slice(start, start + perPage);
+  const nextPage = mergedTimelineNextPage(
+    page,
+    perPage,
+    merged.length,
+    perPartyPages.some((p) => p.nextPage !== void 0)
+  );
+  return { entries: slice, ...nextPage !== void 0 ? { nextPage } : {} };
 }
 var listOpportunityEntriesSchema = z10.object({
   opportunityId: positiveId,
@@ -2137,6 +2290,28 @@ async function removeTagById(input) {
   invalidateByPrefix(TAG_LIST_PATH[entity], "remove_tag_by_id");
   return result;
 }
+var deleteTagDefinitionSchema = z13.object({
+  entity: TagEntity,
+  tagId: positiveId.describe(
+    "The tag definition's id (from list_tags, or embed='tags' on a record). NOT an entity id."
+  ),
+  confirm: confirmFlag().describe(
+    "Must be set to true. DESTRUCTIVE & tenant-wide: permanently deletes the tag DEFINITION from this entity type's tag namespace, removing it from EVERY record that shares it \u2014 not just one. To detach a tag from a single record while keeping the definition, use remove_tag_by_id instead. Irreversible (the definition is gone; re-creating by name via add_tag mints a new id). Idempotent on retry."
+  )
+});
+async function deleteTagDefinition(input) {
+  const { entity, tagId, confirm } = input;
+  if (confirm !== true) {
+    throw new Error("delete_tag_definition requires confirm: true");
+  }
+  const result = await idempotent(
+    () => capsuleDelete(`/${entity}/tags/${tagId}`),
+    () => ({ deleted: true, alreadyDeleted: false, entity, tagId }),
+    () => ({ deleted: true, alreadyDeleted: true, entity, tagId })
+  );
+  invalidateByPrefix(TAG_LIST_PATH[entity], "delete_tag_definition");
+  return result;
+}
 var { schema: batchAddTagSchema, handler: batchAddTag } = defineBatch({
   toolName: "batch_add_tag",
   itemSchema: addTagSchema,
@@ -2642,7 +2817,7 @@ function createCapsuleMcpServer(opts) {
   const server2 = new McpServer(
     {
       name: "capsulemcp",
-      version: "1.6.5",
+      version: "1.8.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
@@ -3060,7 +3235,7 @@ function createCapsuleMcpServer(opts) {
   registerTool(
     server2,
     "list_party_entries",
-    "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.",
+    "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. IMPORTANT for organisations: pass `includeLinkedPersons: true` to surface entries filed against the org's linked people (sales-conversation emails almost always land on a person row, not the org row \u2014 Capsule's API files each entry against exactly one party). Without this flag, an org with active customer-facing email will appear quiet here even though its `lastContactedAt` is current. For any 'what's new with $ORG?' query, set `includeLinkedPersons: true`.",
     listPartyEntriesSchema,
     listPartyEntries
   );
@@ -3097,9 +3272,12 @@ function createCapsuleMcpServer(opts) {
     "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 },
+    // Mirrors the auto-inferred `{readOnlyHint: true, destructiveHint:
+    // false}` that `registerTool` applies to every other `get_*` tool.
+    // Explicit destructiveHint: false is load-bearing — MCP spec
+    // defaults destructiveHint to `true`, so omitting it would (in
+    // some client implementations) classify this read as destructive.
+    { readOnlyHint: true, destructiveHint: false },
     async (input) => {
       const result = await getAttachment(input);
       if (result.truncated) {
@@ -3330,6 +3508,13 @@ function createCapsuleMcpServer(opts) {
       removeTagByIdSchema,
       removeTagById
     );
+    registerTool(
+      server2,
+      "delete_tag_definition",
+      "DESTRUCTIVE & TENANT-WIDE: permanently delete a tag DEFINITION from an entity type's tag namespace (parties / opportunities / kases). Unlike remove_tag_by_id \u2014 which detaches a tag from ONE record and leaves the definition intact for others \u2014 this removes the definition itself, so the tag disappears from EVERY record that shared it. Use it to clean up stray / mistyped / test tag definitions polluting the tenant-global list. Requires confirm=true. Always read the affected tag first via list_tags and confirm with the user; if you only want to untag one record, use remove_tag_by_id instead. Irreversible (re-creating by name via add_tag mints a brand-new id). Idempotent on retry: `{deleted: true, alreadyDeleted: false, entity, tagId}` on a fresh delete, or `{deleted: true, alreadyDeleted: true, entity, tagId}` if the definition was already gone (Capsule's 404 is caught). Endpoint verified empirically (DELETE /<entity>/tags/{id} \u2192 204).",
+      deleteTagDefinitionSchema,
+      deleteTagDefinition
+    );
     registerBatchTool(
       server2,
       "batch_add_tag",
@@ -3369,7 +3554,8 @@ if (!process.env["CAPSULE_API_TOKEN"]) {
   );
   process.exit(1);
 }
-var server = createCapsuleMcpServer();
+var STDIO_CLIENT_ID = "stdio-local";
+var server = createCapsuleMcpServer({ clientId: STDIO_CLIENT_ID });
 var transport = new StdioServerTransport();
 if (isReadOnly()) {
   console.error("[capsulemcp] read-only mode: write/delete tools are not registered");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capsulemcp",
-  "version": "1.6.5",
+  "version": "1.8.0",
   "description": "Model Context Protocol server for Capsule CRM. Lets Claude (Desktop, Code, or web Projects via Custom Connector) read and write your CRM in plain English. Covers contacts, opportunities, projects, tasks, timeline activity, structured filters, saved filters with sort, workflow tracks, file attachments, audit, and batch fetches.",
   "keywords": [
     "mcp",
@@ -62,6 +62,6 @@
     "vitest": "^4.1.7"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.19.0"
   }
 }