capsulemcp 1.6.3 → 1.7.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.
 
-- **86 tools** across the Capsule resource graph (49 in read-only mode) — full read coverage plus careful, confirm-gated writes; 5 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.3"` in `args`. If you're tracking a fork or an unreleased branch, use the GitHub-ref form instead: `"github:soil-dev/capsulemcp#v1.6.3"` — 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.7.0"` in `args`. If you're tracking a fork or an unreleased branch, use the GitHub-ref form instead: `"github:soil-dev/capsulemcp#v1.7.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

@@ -1256,12 +1256,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 [];
@@ -1555,6 +1555,35 @@ function defineDelete(args) {
   return { schema, handler };
 }
 
+// src/tools/preserve-refs.ts
+async function readEntityRefs(path, responseKey) {
+  const { data } = await capsuleGet(path);
+  const entity = data[responseKey];
+  return {
+    teamId: entity?.team?.id ?? void 0,
+    stageId: entity?.stage?.id ?? void 0
+  };
+}
+
+// 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)
+    )
+  );
+  return { [responseKey]: responses.flatMap((r) => r.data[responseKey] ?? []) };
+}
+
 // src/tools/custom-field-helpers.ts
 import { z as z6 } from "zod";
 var CustomFieldWriteSchema = z6.object({
@@ -1677,20 +1706,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,
@@ -1730,8 +1746,11 @@ var PartyWriteBaseSchema = {
   websites: z7.array(WebsiteSchema).optional().describe(
     "APPEND-ONLY: items are merged into the existing list, never replaced. For atomic add/remove/replace use add_party_website and remove_party_website_by_id."
   ),
-  ownerId: positiveId.optional().describe(
-    "Assign to user ID. On create_party, defaults to the API-token owner when omitted. Once set, this connector cannot clear the owner back to null \u2014 use Capsule's web UI for that. Discover IDs via list_users."
+  ownerId: positiveId.nullable().optional().describe(
+    "Pass a user ID to set, or `null` to unassign (verified empirically in v1.6.4 wire-trace \u2014 Capsule accepts `owner: null` on PUT /parties/:id for both persons and organisations). Discover IDs via list_users. WARNING: Capsule's PUT on /parties has the same asymmetric owner/team semantic documented in NOTES-ON-CAPSULE-API.md \xA727 for /kases \u2014 setting `owner` while omitting `team` is plausibly clearing-prone. When you supply `ownerId` and omit `teamId`, this connector reads the party's current team and includes it in the PUT body to preserve it across the owner change. Supply `teamId` explicitly to change it."
+  ),
+  teamId: positiveId.nullable().optional().describe(
+    "Assign to team ID (discover via list_teams). Pass a team ID to set, or `null` to unassign. Capsule enforces the owner\u2208team membership constraint \u2014 passing a team the current owner doesn't belong to returns 422 'owner is not a member of the team'. Combine `ownerId: null` + `teamId: <T>` in one call to transfer a party to team-ownership with no specific user (verified empirically in v1.6.4 wire-trace; the membership rule doesn't fire when owner is null)."
   )
 };
 var createPartySchema = z7.object({
@@ -1744,13 +1763,25 @@ var createPartySchema = z7.object({
   organisationId: positiveId.optional().describe("Link person to an existing organisation ID"),
   // organisation
   name: z7.string().optional(),
-  ...PartyWriteBaseSchema
+  ...PartyWriteBaseSchema,
+  ownerId: positiveId.optional().describe(
+    "Assign to user ID. Defaults to the API-token owner when omitted. To create a team-owned party with no specific user, first create the party, then call update_party with `ownerId: null` and `teamId`."
+  ),
+  teamId: positiveId.optional().describe(
+    "Assign to team ID (discover via list_teams). Omit to leave team unset on create. To clear an existing team or create a team-owned party with no specific owner, use update_party after creation."
+  ),
+  fields: z7.array(CustomFieldWriteSchema).optional().describe(
+    fieldsArrayDescriptor("get_party") + " Verified empirically in v1.6.5 wire-trace: Capsule's POST /parties accepts the same `fields[]` shape as PUT, so callers can set custom field values on creation without a follow-up update."
+  )
 });
 async function createParty(input) {
-  const { ownerId, organisationId, ...rest } = input;
+  const { ownerId, teamId, organisationId, fields, ...rest } = input;
   const body = { ...rest };
   setRef(body, "owner", ownerId);
+  setRef(body, "team", teamId);
   setRef(body, "organisation", organisationId);
+  const mappedFields = mapFieldsForBody(fields);
+  if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/parties", { party: body });
 }
 var updatePartySchema = z7.object({
@@ -1767,12 +1798,17 @@ var updatePartySchema = z7.object({
   ...PartyWriteBaseSchema
 });
 async function updateParty(input) {
-  const { id, ownerId, organisationId, fields, ...rest } = input;
+  const { id, ownerId, teamId, organisationId, fields, ...rest } = input;
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
-  setRef(body, "owner", ownerId);
+  let resolvedTeamId = teamId;
+  if (ownerId !== void 0 && teamId === void 0) {
+    ({ teamId: resolvedTeamId } = await readEntityRefs(`/parties/${id}`, "party"));
+  }
+  setNullableRef(body, "owner", ownerId);
+  setNullableRef(body, "team", resolvedTeamId);
   setNullableRef(body, "organisation", organisationId);
   const mappedFields = mapFieldsForBody(fields);
   if (mappedFields !== void 0) body["fields"] = mappedFields;
@@ -1940,18 +1976,6 @@ async function removePartyWebsiteById(input) {
 
 // src/tools/opportunities.ts
 import { z as z8 } from "zod";
-
-// src/tools/preserve-refs.ts
-async function readEntityRefs(path, responseKey) {
-  const { data } = await capsuleGet(path);
-  const entity = data[responseKey];
-  return {
-    teamId: entity?.team?.id ?? void 0,
-    stageId: entity?.stage?.id ?? void 0
-  };
-}
-
-// src/tools/opportunities.ts
 var OpportunityValueSchema = z8.object({
   amount: z8.number().nonnegative(),
   currency: z8.string({
@@ -1993,23 +2017,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),
@@ -2022,14 +2030,17 @@ var createOpportunitySchema = z8.object({
   expectedCloseOn: z8.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
   probability: z8.number().int().min(0).max(100).optional(),
   ownerId: positiveId.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. WARNING: tenant pipeline / milestone-reached automation can mutate this field post-create \u2014 see the `milestoneId` description for details and the chained-PUT workaround."
+    "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. To clear owner later, call update_opportunity with `ownerId: null`. Discover IDs via list_users. WARNING: tenant pipeline / milestone-reached automation can mutate this field post-create \u2014 see the `milestoneId` description for details and the chained-PUT workaround."
   ),
   teamId: positiveId.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)."
+  ),
+  fields: z8.array(CustomFieldWriteSchema).optional().describe(
+    fieldsArrayDescriptor("get_opportunity") + " Capsule's POST /opportunities accepts the same `fields[]` shape as PUT (inferred by symmetry with the v1.6.5 wire-trace findings on POST /parties and POST /kases \u2014 the tenant probed had no opportunity custom fields configured, so this is unverified empirically). Setting custom fields on creation removes the create-then-update ritual."
   )
 });
 async function createOpportunity(input) {
-  const { partyId, milestoneId, ownerId, teamId, ...rest } = input;
+  const { partyId, milestoneId, ownerId, teamId, fields, ...rest } = input;
   const body = {
     ...rest,
     party: { id: partyId },
@@ -2037,13 +2048,15 @@ async function createOpportunity(input) {
   };
   setRef(body, "owner", ownerId);
   setRef(body, "team", teamId);
+  const mappedFields = mapFieldsForBody(fields);
+  if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/opportunities", { opportunity: body });
 }
 var updateOpportunitySchema = z8.object({
   id: positiveId,
   name: z8.string().min(1).optional(),
   partyId: positiveId.optional().describe(
-    "Reassign the opportunity to a different primary party. Capsule requires every opportunity to have a party \u2014 passing `null` is rejected with 422 'party is required' (use Capsule's web UI if you need to dissolve the link entirely). Discover ids via search_parties / filter_parties. No defensive read-modify-write needed: this connector verified empirically (v1.6.3 wire-trace) that `party` is a standalone PUT field on /opportunities and does not interact with the asymmetric owner/team semantic from NOTES-ON-CAPSULE-API.md \xA727."
+    "Reassign the opportunity to a different primary party. Capsule requires every opportunity to have a party \u2014 passing `null` is rejected with 422 'party is required' (use Capsule's web UI if you need to dissolve the link entirely). Discover ids via search_parties / filter_parties. No defensive read-modify-write needed: this connector verified empirically (v1.6.3 wire-trace) that `party` is a standalone PUT field on /opportunities and does not interact with the asymmetric owner/team semantic from NOTES-ON-CAPSULE-API.md \xA727. NOTE: parent-ref nullability differs by entity \u2014 `update_task.partyId` IS nullable (orphan task), but opportunities and projects must always have a parent party. The same applies to `update_project.partyId`."
   ),
   milestoneId: positiveId.optional().describe(
     "Move the opportunity to this milestone. Side effects depend on the target: closing milestones (Won/Lost) auto-set `closedOn` to today and `probability` to the milestone default (100/0), preserving `lastOpenMilestone` as the previous open stage; moving back to an open milestone clears `closedOn` and re-applies the milestone's default probability (Won/Lost is reversible \u2014 no separate reopen tool). WARNING: Capsule does NOT validate that the new milestone belongs to the opportunity's current pipeline. Passing a milestoneId from a different pipeline silently relocates the opportunity across pipelines, and `lastOpenMilestone` may then reference a milestone in the previous pipeline. Verify against the opportunity's current pipeline (read the opp first, list its pipeline's milestones via list_milestones) before passing a cross-pipeline id. NOTE: changing `milestoneId` can fire **pipeline / milestone-reached automations** that mutate `owner` / `team` on the destination milestone (same shape as `create_opportunity` \u2014 see its `milestoneId` description for the owner-clearing automation caveat). If a milestone-change-and-owner-set in the same call lands with `owner: null`, follow up with a second `update_opportunity` (or `batch_update_opportunity`) carrying both `ownerId` and `teamId` \u2014 milestone-reached triggers only fire on the transition, so a subsequent PUT preserves your values."
@@ -2057,8 +2070,8 @@ var updateOpportunitySchema = z8.object({
   lostReasonId: positiveId.optional().describe(
     "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: positiveId.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. 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."
+  ownerId: positiveId.nullable().optional().describe(
+    "Reassign owner: pass a user ID to set, or `null` to unassign (verified empirically in v1.6.5 wire-trace \u2014 Capsule accepts `owner: null` on PUT /opportunities/:id, mirroring the v1.6.4 finding on /parties; brings update_opportunity into parity with update_party and update_project). 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. Combine `ownerId: null` + `teamId: <T>` in one call to transfer an opportunity to team-ownership with no specific user (verified empirically in v1.6.5; the owner-clears-team semantic doesn't fire when owner is being cleared to null)."
   ),
   teamId: positiveId.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."
@@ -2077,7 +2090,7 @@ async function updateOpportunity(input) {
   if (ownerId !== void 0 && teamId === void 0) {
     ({ teamId: resolvedTeamId } = await readEntityRefs(`/opportunities/${id}`, "opportunity"));
   }
-  setRef(body, "owner", ownerId);
+  setNullableRef(body, "owner", ownerId);
   setNullableRef(body, "team", resolvedTeamId);
   setRef(body, "lostReason", lostReasonId);
   const mappedFields = mapFieldsForBody(fields);
@@ -2132,20 +2145,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),
@@ -2161,10 +2161,13 @@ var createProjectSchema = z9.object({
   stageId: positiveId.optional().describe(
     "Stage (board column) to place the project on. Discover IDs via list_stages \u2014 each stage belongs to one Board, so picking a stageId implicitly picks the board. If omitted, the project is created with no stage assignment (and won't appear on any board). NOTE: tenant-specific board automation rules may run on project creation and mutate `owner` / `team` fields. See `create_project.ownerId` / `create_project.teamId` for the automation caveat. Capsule's create endpoint itself preserves the `ownerId` / `teamId` you supply \u2014 any clearing you observe traces to board automations, not the API."
   ),
-  expectedCloseOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD")
+  expectedCloseOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  fields: z9.array(CustomFieldWriteSchema).optional().describe(
+    fieldsArrayDescriptor("get_project") + " Verified empirically in v1.6.5 wire-trace: Capsule's POST /kases accepts the same `fields[]` shape as PUT, so callers can set custom field values on creation without a follow-up update. Project-specific: setting a field whose definition lives under a 'data tag' populates the row's internal tagId but does NOT auto-add the data tag to the project's tags array \u2014 use add_tag explicitly if you want it visible via embed=tags."
+  )
 });
 async function createProject(input) {
-  const { partyId, ownerId, teamId, status, stageId, ...rest } = input;
+  const { partyId, ownerId, teamId, status, stageId, fields, ...rest } = input;
   const body = {
     ...rest,
     status: status ?? "OPEN",
@@ -2173,6 +2176,8 @@ async function createProject(input) {
   setRef(body, "owner", ownerId);
   setRef(body, "team", teamId);
   if (stageId) body["stage"] = stageId;
+  const mappedFields = mapFieldsForBody(fields);
+  if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/kases", { kase: body });
 }
 var updateProjectSchema = z9.object({
@@ -2181,7 +2186,7 @@ var updateProjectSchema = z9.object({
   description: z9.string().optional(),
   status: z9.enum(["OPEN", "CLOSED"]).optional(),
   partyId: positiveId.optional().describe(
-    "Reassign the project to a different primary party. Capsule requires every project to have a party \u2014 passing `null` is rejected with 422 'party is required' (verified empirically in v1.6.3 wire-trace). Discover ids via search_parties / filter_parties."
+    "Reassign the project to a different primary party. Capsule requires every project to have a party \u2014 passing `null` is rejected with 422 'party is required' (verified empirically in v1.6.3 wire-trace). Discover ids via search_parties / filter_parties. NOTE: parent-ref nullability differs by entity \u2014 `update_task.partyId` IS nullable (orphan task), but opportunities and projects must always have a parent party. The same applies to `update_opportunity.partyId`."
   ),
   ownerId: positiveId.nullable().optional().describe(
     "Reassign owner: pass a user ID to set, or `null` to unassign (matches the 'Unassign' option in Capsule's web UI). When you supply `ownerId` and omit `teamId` and/or `stageId`, the connector fetches the project's current omitted fields and includes them in the PUT body \u2014 this preserves them across the owner change (without it, Capsule's PUT would clear team; stage carry is defensive against the symmetric clear). Supply `teamId` and/or `stageId` explicitly on the same call to change them instead. `teamId: null` clears the team as part of an owner change. Constraints (Capsule enforces, 422 on violation): owner must be a member of the team if both are set; a project must always have at least one of {owner, team} set (cannot clear both)."
@@ -2189,8 +2194,8 @@ var updateProjectSchema = z9.object({
   teamId: positiveId.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_project { 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'. A project must always have at least one of {owner, team} set \u2014 `teamId: null` on a project whose owner is already null returns 422 'owner or team is required'."
   ),
-  stageId: positiveId.optional().describe(
-    "Move the project to this stage (board column). Discover IDs via list_stages. Owner and team are preserved across stage-only updates (Capsule's PUT semantic). WARNING (cross-board): Capsule does NOT validate that the new stage belongs to the project's current board \u2014 passing a stageId from a different board silently relocates the project across boards. Team and other board-derived defaults are NOT updated to match the new board. Verify against the project's current board (read the project first, list its board's stages) before passing a cross-board id."
+  stageId: positiveId.nullable().optional().describe(
+    "Move the project to this stage (board column), or `null` to remove from all stages (verified empirically in v1.6.5 wire-trace \u2014 Capsule accepts `stage: null` on PUT /kases/:id and the project no longer appears on any board). Discover IDs via list_stages. Owner and team are preserved across stage-only updates (Capsule's PUT semantic). WARNING (cross-board): Capsule does NOT validate that the new stage belongs to the project's current board \u2014 passing a stageId from a different board silently relocates the project across boards. Team and other board-derived defaults are NOT updated to match the new board. Verify against the project's current board (read the project first, list its board's stages) before passing a cross-board id."
   ),
   expectedCloseOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
   fields: z9.array(CustomFieldWriteSchema).optional().describe(
@@ -2213,11 +2218,18 @@ async function updateProject(input) {
   }
   setNullableRef(body, "owner", ownerId);
   setNullableRef(body, "team", resolvedTeamId);
-  if (resolvedStageId) body["stage"] = resolvedStageId;
+  if (resolvedStageId === null) body["stage"] = null;
+  else if (resolvedStageId !== void 0) body["stage"] = resolvedStageId;
   const mappedFields = mapFieldsForBody(fields);
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePut(`/kases/${id}`, { kase: body });
 }
+var { schema: batchUpdateProjectSchema, handler: batchUpdateProject } = defineBatch({
+  toolName: "batch_update_project",
+  itemSchema: updateProjectSchema,
+  itemDescription: "Array of 1\u201350 update_project inputs. Each item is the same shape as a single update_project 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). Mirrors batch_update_party and batch_update_opportunity \u2014 same shape across the three entity types.",
+  itemHandler: updateProject
+});
 var { schema: deleteProjectSchema, handler: deleteProject } = defineDelete({
   toolName: "delete_project",
   pathPrefix: "/kases",
@@ -2265,16 +2277,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),
@@ -2317,7 +2320,7 @@ var updateTaskSchema = z10.object({
     "Reassign owner to user ID. Once set, this connector cannot clear an owner back to null \u2014 use Capsule's web UI for that."
   ),
   partyId: positiveId.nullable().optional().describe(
-    "Re-link the task to a party by id, or `null` to orphan it. Mutually exclusive with `opportunityId` / `projectId` \u2014 Capsule enforces 'task can be related to at most one entity' server-side (422 if two parent-refs are set at once, verified in v1.6.3 wire-trace). To swap parent type atomically, pass the old one as `null` and the new one as an id in the same call."
+    "Re-link the task to a party by id, or `null` to orphan it. Mutually exclusive with `opportunityId` / `projectId` \u2014 Capsule enforces 'task can be related to at most one entity' server-side (422 if two parent-refs are set at once, verified in v1.6.3 wire-trace). To swap parent type atomically, pass the old one as `null` and the new one as an id in the same call. NOTE: orphaning is unique to tasks \u2014 `update_opportunity.partyId` and `update_project.partyId` are NOT nullable (Capsule rejects with 422 'party is required'). Tasks are the only entity in Capsule's data model that can exist without any parent."
   ),
   opportunityId: positiveId.nullable().optional().describe(
     "Re-link the task to an opportunity by id, or `null` to orphan it. Mutually exclusive with `partyId` / `projectId` \u2014 see `partyId` for the XOR semantic."
@@ -2375,14 +2378,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,
@@ -2605,6 +2696,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,
@@ -3110,7 +3223,7 @@ function createCapsuleMcpServer(opts) {
   const server = new McpServer(
     {
       name: "capsulemcp",
-      version: "1.6.3",
+      version: "1.7.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
@@ -3206,14 +3319,14 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "create_party",
-      "Create a new person or organisation in Capsule CRM. For type='person', firstName or lastName is required (one suffices); the `name` field is silently ignored. For type='organisation', `name` is required and firstName/lastName/title/jobTitle are silently ignored. Passing organisationId pointing at a non-organisation party (e.g. another person's id) returns 404 'organisation not found' \u2014 Capsule filters lookups by type.",
+      "Create a new person or organisation in Capsule CRM. For type='person', firstName or lastName is required (one suffices); the `name` field is silently ignored. For type='organisation', `name` is required and firstName/lastName/title/jobTitle are silently ignored. Passing organisationId pointing at a non-organisation party (e.g. another person's id) returns 404 'organisation not found' \u2014 Capsule filters lookups by type. Accepts `ownerId` and `teamId` to set ownership at create time; both are optional and Capsule defaults `owner` to the API-token user when omitted (team has no default).",
       createPartySchema,
       createParty
     );
     registerTool(
       server,
       "update_party",
-      "Update top-level fields on an existing party (about, firstName/lastName/name/title/jobTitle, ownerId, organisationId). For PERSON parties, organisationId links to an organisation or null unlinks the person from its organisation; for ORGANISATION parties Capsule silently ignores organisationId. Only the fields you provide are changed. Child arrays (emailAddresses / phoneNumbers / addresses / websites) on this tool are APPEND-ONLY: items are merged into the existing list, not replaced. For surgical changes \u2014 replacing one email, removing one phone number, fixing the type on one address \u2014 use the dedicated atomic tools: add_party_email_address / remove_party_email_address_by_id (and the phone/address/website equivalents).",
+      "Update top-level fields on an existing party (about, firstName/lastName/name/title/jobTitle, ownerId, teamId, organisationId). `ownerId` and `teamId` both accept `null` to unassign \u2014 the combination `{ownerId: null, teamId: <id>}` puts a party into 'team-owned, no specific user' state (the common pattern when transferring ownership to a team after a user departs). For PERSON parties, organisationId links to an organisation or null unlinks; for ORGANISATION parties Capsule silently ignores organisationId. Only the fields you provide are changed. Child arrays (emailAddresses / phoneNumbers / addresses / websites) on this tool are APPEND-ONLY: items are merged into the existing list, not replaced. For surgical changes \u2014 replacing one email, removing one phone number, fixing the type on one address \u2014 use the dedicated atomic tools: add_party_email_address / remove_party_email_address_by_id (and the phone/address/website equivalents).",
       updatePartySchema,
       updateParty
     );
@@ -3348,7 +3461,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "update_opportunity",
-      "Update fields on an existing opportunity, including the parent-reference field `partyId` to reassign the opp to a different primary party. Only the fields you provide are changed. Closed (Won/Lost) opportunities ARE editable \u2014 Capsule does not enforce closed-record immutability, so `value`, `description`, etc. can be changed on a Won opp without warning. If the workflow needs historical revenue numbers to be stable, enforce that caller-side. Capsule requires every opportunity to have a party \u2014 passing `partyId: null` is rejected with 422 'party is required'.",
+      "Update fields on an existing opportunity, including the parent-reference field `partyId` to reassign the opp to a different primary party. `ownerId` and `teamId` both accept `null` to unassign (verified empirically in v1.6.5 wire-trace \u2014 brings update_opportunity into parity with update_party and update_project). The combination `{ownerId: null, teamId: <id>}` puts an opportunity into 'team-owned, no specific user' state, matching the pattern available on parties and projects. Only the fields you provide are changed. Closed (Won/Lost) opportunities ARE editable \u2014 Capsule does not enforce closed-record immutability, so `value`, `description`, etc. can be changed on a Won opp without warning. If the workflow needs historical revenue numbers to be stable, enforce that caller-side. Capsule requires every opportunity to have a party \u2014 passing `partyId: null` is rejected with 422 'party is required' (Unlike `update_task.partyId` which IS nullable \u2014 tasks can be orphaned in Capsule's model).",
       updateOpportunitySchema,
       updateOpportunity
     );
@@ -3413,10 +3526,17 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "update_project",
-      "Update fields on an existing project, including the parent-reference field `partyId` to reassign the project to a different primary party. Only the fields you provide are changed. Use status='CLOSED' to close a project. CLOSED projects remain fully editable \u2014 Capsule does not enforce closed-record immutability. Stage moves and description edits on a CLOSED project are accepted without warning. Capsule requires every project to have a party \u2014 passing `partyId: null` is rejected with 422 'party is required'.",
+      "Update fields on an existing project, including the parent-reference field `partyId` to reassign the project to a different primary party. `ownerId`, `teamId`, and `stageId` all accept `null` to unassign (the latter removes the project from all stages \u2014 verified empirically in v1.6.5 wire-trace). Constraint: a project must always have at least one of {owner, team} set, so `teamId: null` on a project with no owner returns 422. Only the fields you provide are changed. Use status='CLOSED' to close a project. CLOSED projects remain fully editable \u2014 Capsule does not enforce closed-record immutability. Stage moves and description edits on a CLOSED project are accepted without warning. Capsule requires every project to have a party \u2014 passing `partyId: null` is rejected with 422 'party is required' (Unlike `update_task.partyId` which IS nullable \u2014 tasks can be orphaned in Capsule's model).",
       updateProjectSchema,
       updateProject
     );
+    registerBatchTool(
+      server,
+      "batch_update_project",
+      "Update 1\u201350 projects in parallel. Same input shape as update_project but wrapped in an `items` array. Use this \u2014 not N sequential update_project calls \u2014 for mass stage transitions (e.g. move a board column of projects to a new stage), bulk owner reassignments after a personnel change, or batch closures. Mirrors batch_update_party and batch_update_opportunity \u2014 identical fan-out shape across the three entity types. 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.",
+      batchUpdateProjectSchema,
+      batchUpdateProject
+    );
     registerTool(
       server,
       "delete_project",
@@ -3521,7 +3641,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
   );
@@ -3558,9 +3678,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) {
@@ -3791,6 +3914,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",
@@ -3908,6 +4038,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

@@ -753,12 +753,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 [];
@@ -1052,6 +1052,35 @@ function defineDelete(args) {
   return { schema, handler };
 }
 
+// src/tools/preserve-refs.ts
+async function readEntityRefs(path, responseKey) {
+  const { data } = await capsuleGet(path);
+  const entity = data[responseKey];
+  return {
+    teamId: entity?.team?.id ?? void 0,
+    stageId: entity?.stage?.id ?? void 0
+  };
+}
+
+// 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)
+    )
+  );
+  return { [responseKey]: responses.flatMap((r) => r.data[responseKey] ?? []) };
+}
+
 // src/tools/custom-field-helpers.ts
 import { z as z5 } from "zod";
 var CustomFieldWriteSchema = z5.object({
@@ -1174,20 +1203,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,
@@ -1227,8 +1243,11 @@ var PartyWriteBaseSchema = {
   websites: z6.array(WebsiteSchema).optional().describe(
     "APPEND-ONLY: items are merged into the existing list, never replaced. For atomic add/remove/replace use add_party_website and remove_party_website_by_id."
   ),
-  ownerId: positiveId.optional().describe(
-    "Assign to user ID. On create_party, defaults to the API-token owner when omitted. Once set, this connector cannot clear the owner back to null \u2014 use Capsule's web UI for that. Discover IDs via list_users."
+  ownerId: positiveId.nullable().optional().describe(
+    "Pass a user ID to set, or `null` to unassign (verified empirically in v1.6.4 wire-trace \u2014 Capsule accepts `owner: null` on PUT /parties/:id for both persons and organisations). Discover IDs via list_users. WARNING: Capsule's PUT on /parties has the same asymmetric owner/team semantic documented in NOTES-ON-CAPSULE-API.md \xA727 for /kases \u2014 setting `owner` while omitting `team` is plausibly clearing-prone. When you supply `ownerId` and omit `teamId`, this connector reads the party's current team and includes it in the PUT body to preserve it across the owner change. Supply `teamId` explicitly to change it."
+  ),
+  teamId: positiveId.nullable().optional().describe(
+    "Assign to team ID (discover via list_teams). Pass a team ID to set, or `null` to unassign. Capsule enforces the owner\u2208team membership constraint \u2014 passing a team the current owner doesn't belong to returns 422 'owner is not a member of the team'. Combine `ownerId: null` + `teamId: <T>` in one call to transfer a party to team-ownership with no specific user (verified empirically in v1.6.4 wire-trace; the membership rule doesn't fire when owner is null)."
   )
 };
 var createPartySchema = z6.object({
@@ -1241,13 +1260,25 @@ var createPartySchema = z6.object({
   organisationId: positiveId.optional().describe("Link person to an existing organisation ID"),
   // organisation
   name: z6.string().optional(),
-  ...PartyWriteBaseSchema
+  ...PartyWriteBaseSchema,
+  ownerId: positiveId.optional().describe(
+    "Assign to user ID. Defaults to the API-token owner when omitted. To create a team-owned party with no specific user, first create the party, then call update_party with `ownerId: null` and `teamId`."
+  ),
+  teamId: positiveId.optional().describe(
+    "Assign to team ID (discover via list_teams). Omit to leave team unset on create. To clear an existing team or create a team-owned party with no specific owner, use update_party after creation."
+  ),
+  fields: z6.array(CustomFieldWriteSchema).optional().describe(
+    fieldsArrayDescriptor("get_party") + " Verified empirically in v1.6.5 wire-trace: Capsule's POST /parties accepts the same `fields[]` shape as PUT, so callers can set custom field values on creation without a follow-up update."
+  )
 });
 async function createParty(input) {
-  const { ownerId, organisationId, ...rest } = input;
+  const { ownerId, teamId, organisationId, fields, ...rest } = input;
   const body = { ...rest };
   setRef(body, "owner", ownerId);
+  setRef(body, "team", teamId);
   setRef(body, "organisation", organisationId);
+  const mappedFields = mapFieldsForBody(fields);
+  if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/parties", { party: body });
 }
 var updatePartySchema = z6.object({
@@ -1264,12 +1295,17 @@ var updatePartySchema = z6.object({
   ...PartyWriteBaseSchema
 });
 async function updateParty(input) {
-  const { id, ownerId, organisationId, fields, ...rest } = input;
+  const { id, ownerId, teamId, organisationId, fields, ...rest } = input;
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
-  setRef(body, "owner", ownerId);
+  let resolvedTeamId = teamId;
+  if (ownerId !== void 0 && teamId === void 0) {
+    ({ teamId: resolvedTeamId } = await readEntityRefs(`/parties/${id}`, "party"));
+  }
+  setNullableRef(body, "owner", ownerId);
+  setNullableRef(body, "team", resolvedTeamId);
   setNullableRef(body, "organisation", organisationId);
   const mappedFields = mapFieldsForBody(fields);
   if (mappedFields !== void 0) body["fields"] = mappedFields;
@@ -1437,18 +1473,6 @@ async function removePartyWebsiteById(input) {
 
 // src/tools/opportunities.ts
 import { z as z7 } from "zod";
-
-// src/tools/preserve-refs.ts
-async function readEntityRefs(path, responseKey) {
-  const { data } = await capsuleGet(path);
-  const entity = data[responseKey];
-  return {
-    teamId: entity?.team?.id ?? void 0,
-    stageId: entity?.stage?.id ?? void 0
-  };
-}
-
-// src/tools/opportunities.ts
 var OpportunityValueSchema = z7.object({
   amount: z7.number().nonnegative(),
   currency: z7.string({
@@ -1490,23 +1514,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),
@@ -1519,14 +1527,17 @@ var createOpportunitySchema = z7.object({
   expectedCloseOn: z7.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
   probability: z7.number().int().min(0).max(100).optional(),
   ownerId: positiveId.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. WARNING: tenant pipeline / milestone-reached automation can mutate this field post-create \u2014 see the `milestoneId` description for details and the chained-PUT workaround."
+    "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. To clear owner later, call update_opportunity with `ownerId: null`. Discover IDs via list_users. WARNING: tenant pipeline / milestone-reached automation can mutate this field post-create \u2014 see the `milestoneId` description for details and the chained-PUT workaround."
   ),
   teamId: positiveId.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)."
+  ),
+  fields: z7.array(CustomFieldWriteSchema).optional().describe(
+    fieldsArrayDescriptor("get_opportunity") + " Capsule's POST /opportunities accepts the same `fields[]` shape as PUT (inferred by symmetry with the v1.6.5 wire-trace findings on POST /parties and POST /kases \u2014 the tenant probed had no opportunity custom fields configured, so this is unverified empirically). Setting custom fields on creation removes the create-then-update ritual."
   )
 });
 async function createOpportunity(input) {
-  const { partyId, milestoneId, ownerId, teamId, ...rest } = input;
+  const { partyId, milestoneId, ownerId, teamId, fields, ...rest } = input;
   const body = {
     ...rest,
     party: { id: partyId },
@@ -1534,13 +1545,15 @@ async function createOpportunity(input) {
   };
   setRef(body, "owner", ownerId);
   setRef(body, "team", teamId);
+  const mappedFields = mapFieldsForBody(fields);
+  if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/opportunities", { opportunity: body });
 }
 var updateOpportunitySchema = z7.object({
   id: positiveId,
   name: z7.string().min(1).optional(),
   partyId: positiveId.optional().describe(
-    "Reassign the opportunity to a different primary party. Capsule requires every opportunity to have a party \u2014 passing `null` is rejected with 422 'party is required' (use Capsule's web UI if you need to dissolve the link entirely). Discover ids via search_parties / filter_parties. No defensive read-modify-write needed: this connector verified empirically (v1.6.3 wire-trace) that `party` is a standalone PUT field on /opportunities and does not interact with the asymmetric owner/team semantic from NOTES-ON-CAPSULE-API.md \xA727."
+    "Reassign the opportunity to a different primary party. Capsule requires every opportunity to have a party \u2014 passing `null` is rejected with 422 'party is required' (use Capsule's web UI if you need to dissolve the link entirely). Discover ids via search_parties / filter_parties. No defensive read-modify-write needed: this connector verified empirically (v1.6.3 wire-trace) that `party` is a standalone PUT field on /opportunities and does not interact with the asymmetric owner/team semantic from NOTES-ON-CAPSULE-API.md \xA727. NOTE: parent-ref nullability differs by entity \u2014 `update_task.partyId` IS nullable (orphan task), but opportunities and projects must always have a parent party. The same applies to `update_project.partyId`."
   ),
   milestoneId: positiveId.optional().describe(
     "Move the opportunity to this milestone. Side effects depend on the target: closing milestones (Won/Lost) auto-set `closedOn` to today and `probability` to the milestone default (100/0), preserving `lastOpenMilestone` as the previous open stage; moving back to an open milestone clears `closedOn` and re-applies the milestone's default probability (Won/Lost is reversible \u2014 no separate reopen tool). WARNING: Capsule does NOT validate that the new milestone belongs to the opportunity's current pipeline. Passing a milestoneId from a different pipeline silently relocates the opportunity across pipelines, and `lastOpenMilestone` may then reference a milestone in the previous pipeline. Verify against the opportunity's current pipeline (read the opp first, list its pipeline's milestones via list_milestones) before passing a cross-pipeline id. NOTE: changing `milestoneId` can fire **pipeline / milestone-reached automations** that mutate `owner` / `team` on the destination milestone (same shape as `create_opportunity` \u2014 see its `milestoneId` description for the owner-clearing automation caveat). If a milestone-change-and-owner-set in the same call lands with `owner: null`, follow up with a second `update_opportunity` (or `batch_update_opportunity`) carrying both `ownerId` and `teamId` \u2014 milestone-reached triggers only fire on the transition, so a subsequent PUT preserves your values."
@@ -1554,8 +1567,8 @@ var updateOpportunitySchema = z7.object({
   lostReasonId: positiveId.optional().describe(
     "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: positiveId.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. 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."
+  ownerId: positiveId.nullable().optional().describe(
+    "Reassign owner: pass a user ID to set, or `null` to unassign (verified empirically in v1.6.5 wire-trace \u2014 Capsule accepts `owner: null` on PUT /opportunities/:id, mirroring the v1.6.4 finding on /parties; brings update_opportunity into parity with update_party and update_project). 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. Combine `ownerId: null` + `teamId: <T>` in one call to transfer an opportunity to team-ownership with no specific user (verified empirically in v1.6.5; the owner-clears-team semantic doesn't fire when owner is being cleared to null)."
   ),
   teamId: positiveId.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."
@@ -1574,7 +1587,7 @@ async function updateOpportunity(input) {
   if (ownerId !== void 0 && teamId === void 0) {
     ({ teamId: resolvedTeamId } = await readEntityRefs(`/opportunities/${id}`, "opportunity"));
   }
-  setRef(body, "owner", ownerId);
+  setNullableRef(body, "owner", ownerId);
   setNullableRef(body, "team", resolvedTeamId);
   setRef(body, "lostReason", lostReasonId);
   const mappedFields = mapFieldsForBody(fields);
@@ -1629,20 +1642,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),
@@ -1658,10 +1658,13 @@ var createProjectSchema = z8.object({
   stageId: positiveId.optional().describe(
     "Stage (board column) to place the project on. Discover IDs via list_stages \u2014 each stage belongs to one Board, so picking a stageId implicitly picks the board. If omitted, the project is created with no stage assignment (and won't appear on any board). NOTE: tenant-specific board automation rules may run on project creation and mutate `owner` / `team` fields. See `create_project.ownerId` / `create_project.teamId` for the automation caveat. Capsule's create endpoint itself preserves the `ownerId` / `teamId` you supply \u2014 any clearing you observe traces to board automations, not the API."
   ),
-  expectedCloseOn: z8.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD")
+  expectedCloseOn: z8.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  fields: z8.array(CustomFieldWriteSchema).optional().describe(
+    fieldsArrayDescriptor("get_project") + " Verified empirically in v1.6.5 wire-trace: Capsule's POST /kases accepts the same `fields[]` shape as PUT, so callers can set custom field values on creation without a follow-up update. Project-specific: setting a field whose definition lives under a 'data tag' populates the row's internal tagId but does NOT auto-add the data tag to the project's tags array \u2014 use add_tag explicitly if you want it visible via embed=tags."
+  )
 });
 async function createProject(input) {
-  const { partyId, ownerId, teamId, status, stageId, ...rest } = input;
+  const { partyId, ownerId, teamId, status, stageId, fields, ...rest } = input;
   const body = {
     ...rest,
     status: status ?? "OPEN",
@@ -1670,6 +1673,8 @@ async function createProject(input) {
   setRef(body, "owner", ownerId);
   setRef(body, "team", teamId);
   if (stageId) body["stage"] = stageId;
+  const mappedFields = mapFieldsForBody(fields);
+  if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/kases", { kase: body });
 }
 var updateProjectSchema = z8.object({
@@ -1678,7 +1683,7 @@ var updateProjectSchema = z8.object({
   description: z8.string().optional(),
   status: z8.enum(["OPEN", "CLOSED"]).optional(),
   partyId: positiveId.optional().describe(
-    "Reassign the project to a different primary party. Capsule requires every project to have a party \u2014 passing `null` is rejected with 422 'party is required' (verified empirically in v1.6.3 wire-trace). Discover ids via search_parties / filter_parties."
+    "Reassign the project to a different primary party. Capsule requires every project to have a party \u2014 passing `null` is rejected with 422 'party is required' (verified empirically in v1.6.3 wire-trace). Discover ids via search_parties / filter_parties. NOTE: parent-ref nullability differs by entity \u2014 `update_task.partyId` IS nullable (orphan task), but opportunities and projects must always have a parent party. The same applies to `update_opportunity.partyId`."
   ),
   ownerId: positiveId.nullable().optional().describe(
     "Reassign owner: pass a user ID to set, or `null` to unassign (matches the 'Unassign' option in Capsule's web UI). When you supply `ownerId` and omit `teamId` and/or `stageId`, the connector fetches the project's current omitted fields and includes them in the PUT body \u2014 this preserves them across the owner change (without it, Capsule's PUT would clear team; stage carry is defensive against the symmetric clear). Supply `teamId` and/or `stageId` explicitly on the same call to change them instead. `teamId: null` clears the team as part of an owner change. Constraints (Capsule enforces, 422 on violation): owner must be a member of the team if both are set; a project must always have at least one of {owner, team} set (cannot clear both)."
@@ -1686,8 +1691,8 @@ var updateProjectSchema = z8.object({
   teamId: positiveId.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_project { 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'. A project must always have at least one of {owner, team} set \u2014 `teamId: null` on a project whose owner is already null returns 422 'owner or team is required'."
   ),
-  stageId: positiveId.optional().describe(
-    "Move the project to this stage (board column). Discover IDs via list_stages. Owner and team are preserved across stage-only updates (Capsule's PUT semantic). WARNING (cross-board): Capsule does NOT validate that the new stage belongs to the project's current board \u2014 passing a stageId from a different board silently relocates the project across boards. Team and other board-derived defaults are NOT updated to match the new board. Verify against the project's current board (read the project first, list its board's stages) before passing a cross-board id."
+  stageId: positiveId.nullable().optional().describe(
+    "Move the project to this stage (board column), or `null` to remove from all stages (verified empirically in v1.6.5 wire-trace \u2014 Capsule accepts `stage: null` on PUT /kases/:id and the project no longer appears on any board). Discover IDs via list_stages. Owner and team are preserved across stage-only updates (Capsule's PUT semantic). WARNING (cross-board): Capsule does NOT validate that the new stage belongs to the project's current board \u2014 passing a stageId from a different board silently relocates the project across boards. Team and other board-derived defaults are NOT updated to match the new board. Verify against the project's current board (read the project first, list its board's stages) before passing a cross-board id."
   ),
   expectedCloseOn: z8.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
   fields: z8.array(CustomFieldWriteSchema).optional().describe(
@@ -1710,11 +1715,18 @@ async function updateProject(input) {
   }
   setNullableRef(body, "owner", ownerId);
   setNullableRef(body, "team", resolvedTeamId);
-  if (resolvedStageId) body["stage"] = resolvedStageId;
+  if (resolvedStageId === null) body["stage"] = null;
+  else if (resolvedStageId !== void 0) body["stage"] = resolvedStageId;
   const mappedFields = mapFieldsForBody(fields);
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePut(`/kases/${id}`, { kase: body });
 }
+var { schema: batchUpdateProjectSchema, handler: batchUpdateProject } = defineBatch({
+  toolName: "batch_update_project",
+  itemSchema: updateProjectSchema,
+  itemDescription: "Array of 1\u201350 update_project inputs. Each item is the same shape as a single update_project 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). Mirrors batch_update_party and batch_update_opportunity \u2014 same shape across the three entity types.",
+  itemHandler: updateProject
+});
 var { schema: deleteProjectSchema, handler: deleteProject } = defineDelete({
   toolName: "delete_project",
   pathPrefix: "/kases",
@@ -1762,16 +1774,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),
@@ -1814,7 +1817,7 @@ var updateTaskSchema = z9.object({
     "Reassign owner to user ID. Once set, this connector cannot clear an owner back to null \u2014 use Capsule's web UI for that."
   ),
   partyId: positiveId.nullable().optional().describe(
-    "Re-link the task to a party by id, or `null` to orphan it. Mutually exclusive with `opportunityId` / `projectId` \u2014 Capsule enforces 'task can be related to at most one entity' server-side (422 if two parent-refs are set at once, verified in v1.6.3 wire-trace). To swap parent type atomically, pass the old one as `null` and the new one as an id in the same call."
+    "Re-link the task to a party by id, or `null` to orphan it. Mutually exclusive with `opportunityId` / `projectId` \u2014 Capsule enforces 'task can be related to at most one entity' server-side (422 if two parent-refs are set at once, verified in v1.6.3 wire-trace). To swap parent type atomically, pass the old one as `null` and the new one as an id in the same call. NOTE: orphaning is unique to tasks \u2014 `update_opportunity.partyId` and `update_project.partyId` are NOT nullable (Capsule rejects with 422 'party is required'). Tasks are the only entity in Capsule's data model that can exist without any parent."
   ),
   opportunityId: positiveId.nullable().optional().describe(
     "Re-link the task to an opportunity by id, or `null` to orphan it. Mutually exclusive with `partyId` / `projectId` \u2014 see `partyId` for the XOR semantic."
@@ -1872,14 +1875,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,
@@ -2102,6 +2193,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,
@@ -2607,7 +2720,7 @@ function createCapsuleMcpServer(opts) {
   const server2 = new McpServer(
     {
       name: "capsulemcp",
-      version: "1.6.3",
+      version: "1.7.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
@@ -2703,14 +2816,14 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server2,
       "create_party",
-      "Create a new person or organisation in Capsule CRM. For type='person', firstName or lastName is required (one suffices); the `name` field is silently ignored. For type='organisation', `name` is required and firstName/lastName/title/jobTitle are silently ignored. Passing organisationId pointing at a non-organisation party (e.g. another person's id) returns 404 'organisation not found' \u2014 Capsule filters lookups by type.",
+      "Create a new person or organisation in Capsule CRM. For type='person', firstName or lastName is required (one suffices); the `name` field is silently ignored. For type='organisation', `name` is required and firstName/lastName/title/jobTitle are silently ignored. Passing organisationId pointing at a non-organisation party (e.g. another person's id) returns 404 'organisation not found' \u2014 Capsule filters lookups by type. Accepts `ownerId` and `teamId` to set ownership at create time; both are optional and Capsule defaults `owner` to the API-token user when omitted (team has no default).",
       createPartySchema,
       createParty
     );
     registerTool(
       server2,
       "update_party",
-      "Update top-level fields on an existing party (about, firstName/lastName/name/title/jobTitle, ownerId, organisationId). For PERSON parties, organisationId links to an organisation or null unlinks the person from its organisation; for ORGANISATION parties Capsule silently ignores organisationId. Only the fields you provide are changed. Child arrays (emailAddresses / phoneNumbers / addresses / websites) on this tool are APPEND-ONLY: items are merged into the existing list, not replaced. For surgical changes \u2014 replacing one email, removing one phone number, fixing the type on one address \u2014 use the dedicated atomic tools: add_party_email_address / remove_party_email_address_by_id (and the phone/address/website equivalents).",
+      "Update top-level fields on an existing party (about, firstName/lastName/name/title/jobTitle, ownerId, teamId, organisationId). `ownerId` and `teamId` both accept `null` to unassign \u2014 the combination `{ownerId: null, teamId: <id>}` puts a party into 'team-owned, no specific user' state (the common pattern when transferring ownership to a team after a user departs). For PERSON parties, organisationId links to an organisation or null unlinks; for ORGANISATION parties Capsule silently ignores organisationId. Only the fields you provide are changed. Child arrays (emailAddresses / phoneNumbers / addresses / websites) on this tool are APPEND-ONLY: items are merged into the existing list, not replaced. For surgical changes \u2014 replacing one email, removing one phone number, fixing the type on one address \u2014 use the dedicated atomic tools: add_party_email_address / remove_party_email_address_by_id (and the phone/address/website equivalents).",
       updatePartySchema,
       updateParty
     );
@@ -2845,7 +2958,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server2,
       "update_opportunity",
-      "Update fields on an existing opportunity, including the parent-reference field `partyId` to reassign the opp to a different primary party. Only the fields you provide are changed. Closed (Won/Lost) opportunities ARE editable \u2014 Capsule does not enforce closed-record immutability, so `value`, `description`, etc. can be changed on a Won opp without warning. If the workflow needs historical revenue numbers to be stable, enforce that caller-side. Capsule requires every opportunity to have a party \u2014 passing `partyId: null` is rejected with 422 'party is required'.",
+      "Update fields on an existing opportunity, including the parent-reference field `partyId` to reassign the opp to a different primary party. `ownerId` and `teamId` both accept `null` to unassign (verified empirically in v1.6.5 wire-trace \u2014 brings update_opportunity into parity with update_party and update_project). The combination `{ownerId: null, teamId: <id>}` puts an opportunity into 'team-owned, no specific user' state, matching the pattern available on parties and projects. Only the fields you provide are changed. Closed (Won/Lost) opportunities ARE editable \u2014 Capsule does not enforce closed-record immutability, so `value`, `description`, etc. can be changed on a Won opp without warning. If the workflow needs historical revenue numbers to be stable, enforce that caller-side. Capsule requires every opportunity to have a party \u2014 passing `partyId: null` is rejected with 422 'party is required' (Unlike `update_task.partyId` which IS nullable \u2014 tasks can be orphaned in Capsule's model).",
       updateOpportunitySchema,
       updateOpportunity
     );
@@ -2910,10 +3023,17 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server2,
       "update_project",
-      "Update fields on an existing project, including the parent-reference field `partyId` to reassign the project to a different primary party. Only the fields you provide are changed. Use status='CLOSED' to close a project. CLOSED projects remain fully editable \u2014 Capsule does not enforce closed-record immutability. Stage moves and description edits on a CLOSED project are accepted without warning. Capsule requires every project to have a party \u2014 passing `partyId: null` is rejected with 422 'party is required'.",
+      "Update fields on an existing project, including the parent-reference field `partyId` to reassign the project to a different primary party. `ownerId`, `teamId`, and `stageId` all accept `null` to unassign (the latter removes the project from all stages \u2014 verified empirically in v1.6.5 wire-trace). Constraint: a project must always have at least one of {owner, team} set, so `teamId: null` on a project with no owner returns 422. Only the fields you provide are changed. Use status='CLOSED' to close a project. CLOSED projects remain fully editable \u2014 Capsule does not enforce closed-record immutability. Stage moves and description edits on a CLOSED project are accepted without warning. Capsule requires every project to have a party \u2014 passing `partyId: null` is rejected with 422 'party is required' (Unlike `update_task.partyId` which IS nullable \u2014 tasks can be orphaned in Capsule's model).",
       updateProjectSchema,
       updateProject
     );
+    registerBatchTool(
+      server2,
+      "batch_update_project",
+      "Update 1\u201350 projects in parallel. Same input shape as update_project but wrapped in an `items` array. Use this \u2014 not N sequential update_project calls \u2014 for mass stage transitions (e.g. move a board column of projects to a new stage), bulk owner reassignments after a personnel change, or batch closures. Mirrors batch_update_party and batch_update_opportunity \u2014 identical fan-out shape across the three entity types. 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.",
+      batchUpdateProjectSchema,
+      batchUpdateProject
+    );
     registerTool(
       server2,
       "delete_project",
@@ -3018,7 +3138,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
   );
@@ -3055,9 +3175,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) {
@@ -3288,6 +3411,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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capsulemcp",
-  "version": "1.6.3",
+  "version": "1.7.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",