capsulemcp 1.6.2 → 1.6.5

package/README.md

@@ -4,7 +4,7 @@
 
 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
+- **87 tools** across the Capsule resource graph (49 in read-only mode) — full read coverage plus careful, confirm-gated writes; 6 batched-write tools (`batch_*`) for mass-update workflows
 - **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
@@ -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.2"` in `args`. If you're tracking a fork or an unreleased branch, use the GitHub-ref form instead: `"github:soil-dev/capsulemcp#v1.6.2"` — 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.6.5"` in `args`. If you're tracking a fork or an unreleased branch, use the GitHub-ref form instead: `"github:soil-dev/capsulemcp#v1.6.5"` — same arguments, just installs from a git clone rather than the npm registry. See [INSTALL.md](INSTALL.md) for the Claude Code path, manual install, and troubleshooting.
 
 ## Tools
 

package/dist/http.js

@@ -1555,6 +1555,16 @@ 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/tools/custom-field-helpers.ts
 import { z as z6 } from "zod";
 var CustomFieldWriteSchema = z6.object({
@@ -1730,8 +1740,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 +1757,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({
@@ -1760,16 +1785,25 @@ var updatePartySchema = z7.object({
   title: z7.string().optional(),
   jobTitle: z7.string().optional(),
   name: z7.string().optional(),
+  organisationId: positiveId.nullable().optional().describe(
+    "For PERSON parties: link to an organisation by id, or `null` to unlink (the person becomes an orphan / standalone record). Discover org IDs via search_parties / filter_parties with type=organisation. For ORGANISATION parties: silently ignored by Capsule's API \u2014 organisations don't have a parent organisation in the data model. Empirically verified in v1.6.3 wire-trace; no client-side type guard since the no-op is harmless."
+  ),
   fields: z7.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_party")),
   ...PartyWriteBaseSchema
 });
 async function updateParty(input) {
-  const { id, ownerId, 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;
   return capsulePut(`/parties/${id}`, { party: body });
@@ -1936,18 +1970,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({
@@ -2018,14 +2040,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 },
@@ -2033,11 +2058,16 @@ 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. 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."
   ),
@@ -2050,8 +2080,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."
@@ -2059,17 +2089,18 @@ var updateOpportunitySchema = z8.object({
   fields: z8.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_opportunity"))
 });
 async function updateOpportunity(input) {
-  const { id, milestoneId, ownerId, teamId, lostReasonId, fields, ...rest } = input;
+  const { id, partyId, milestoneId, ownerId, teamId, lostReasonId, fields, ...rest } = input;
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
+  setRef(body, "party", partyId);
   setRef(body, "milestone", milestoneId);
   let resolvedTeamId = teamId;
   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);
@@ -2153,10 +2184,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",
@@ -2165,6 +2199,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({
@@ -2172,14 +2208,17 @@ var updateProjectSchema = z9.object({
   name: z9.string().min(1).optional(),
   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. 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)."
   ),
   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(
@@ -2187,11 +2226,12 @@ var updateProjectSchema = z9.object({
   )
 });
 async function updateProject(input) {
-  const { id, ownerId, teamId, stageId, fields, ...rest } = input;
+  const { id, partyId, ownerId, teamId, stageId, fields, ...rest } = input;
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
+  setRef(body, "party", partyId);
   let resolvedTeamId = teamId;
   let resolvedStageId = stageId;
   if (ownerId !== void 0 && (teamId === void 0 || stageId === void 0)) {
@@ -2201,11 +2241,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",
@@ -2303,15 +2350,33 @@ var updateTaskSchema = z10.object({
   ),
   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."
+  ),
+  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. 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."
+  ),
+  projectId: positiveId.nullable().optional().describe(
+    "Re-link the task to a project (kase) by id, or `null` to orphan it. Mutually exclusive with `partyId` / `opportunityId` \u2014 see `partyId` for the XOR semantic."
   )
 });
 async function updateTask(input) {
-  const { id, ownerId, ...rest } = input;
+  const { id, ownerId, partyId, opportunityId, projectId, ...rest } = input;
+  const setCount = [partyId, opportunityId, projectId].filter((v) => typeof v === "number").length;
+  if (setCount > 1) {
+    throw new Error(
+      "update_task: provide at most one of partyId, opportunityId, or projectId (Capsule rejects multi-parent tasks with 422 'task can be related to at most one entity')"
+    );
+  }
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
   setRef(body, "owner", ownerId);
+  setNullableRef(body, "party", partyId);
+  setNullableRef(body, "opportunity", opportunityId);
+  setNullableRef(body, "kase", projectId);
   return capsulePut(`/tasks/${id}`, { task: body });
 }
 var completeTaskSchema = z10.object({
@@ -3080,7 +3145,7 @@ function createCapsuleMcpServer(opts) {
   const server = new McpServer(
     {
       name: "capsulemcp",
-      version: "1.6.2",
+      version: "1.6.5",
       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
@@ -3176,14 +3241,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). 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
     );
@@ -3318,7 +3383,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "update_opportunity",
-      "Update fields on an existing opportunity. 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.",
+      "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
     );
@@ -3383,10 +3448,17 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "update_project",
-      "Update fields on an existing project. 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.",
+      "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",
@@ -3462,7 +3534,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "update_task",
-      "Update fields on an existing task: `description`, `dueOn`, `dueTime`, `detail`, `status` (OPEN or COMPLETED), and `ownerId`. Only the fields you provide are changed. To mark a task done, prefer the dedicated `complete_task` tool \u2014 it's idempotent (a no-op success on an already-completed task) and semantically clearer than `update_task status=COMPLETED`. Capsule rejects directly setting status=PENDING (which exists only internally for track-driven tasks); use OPEN or COMPLETED. Completed tasks remain fully editable \u2014 Capsule does not enforce closed-record immutability.",
+      "Update fields on an existing task: `description`, `dueOn`, `dueTime`, `detail`, `status` (OPEN or COMPLETED), `ownerId`, and the parent-reference fields `partyId`, `opportunityId`, `projectId`. Pass a parent id to re-link the task, or null on a parent field to orphan/unlink it; at most one parent id may be set in a single call, though null+id swaps are allowed. Only the fields you provide are changed. To mark a task done, prefer the dedicated `complete_task` tool \u2014 it's idempotent (a no-op success on an already-completed task) and semantically clearer than `update_task status=COMPLETED`. Capsule rejects directly setting status=PENDING (which exists only internally for track-driven tasks); use OPEN or COMPLETED. Completed tasks remain fully editable \u2014 Capsule does not enforce closed-record immutability.",
       updateTaskSchema,
       updateTask
     );

package/dist/index.js

@@ -1052,6 +1052,16 @@ 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/tools/custom-field-helpers.ts
 import { z as z5 } from "zod";
 var CustomFieldWriteSchema = z5.object({
@@ -1227,8 +1237,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 +1254,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({
@@ -1257,16 +1282,25 @@ var updatePartySchema = z6.object({
   title: z6.string().optional(),
   jobTitle: z6.string().optional(),
   name: z6.string().optional(),
+  organisationId: positiveId.nullable().optional().describe(
+    "For PERSON parties: link to an organisation by id, or `null` to unlink (the person becomes an orphan / standalone record). Discover org IDs via search_parties / filter_parties with type=organisation. For ORGANISATION parties: silently ignored by Capsule's API \u2014 organisations don't have a parent organisation in the data model. Empirically verified in v1.6.3 wire-trace; no client-side type guard since the no-op is harmless."
+  ),
   fields: z6.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_party")),
   ...PartyWriteBaseSchema
 });
 async function updateParty(input) {
-  const { id, ownerId, 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;
   return capsulePut(`/parties/${id}`, { party: body });
@@ -1433,18 +1467,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({
@@ -1515,14 +1537,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 },
@@ -1530,11 +1555,16 @@ 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. 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."
   ),
@@ -1547,8 +1577,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."
@@ -1556,17 +1586,18 @@ var updateOpportunitySchema = z7.object({
   fields: z7.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_opportunity"))
 });
 async function updateOpportunity(input) {
-  const { id, milestoneId, ownerId, teamId, lostReasonId, fields, ...rest } = input;
+  const { id, partyId, milestoneId, ownerId, teamId, lostReasonId, fields, ...rest } = input;
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
+  setRef(body, "party", partyId);
   setRef(body, "milestone", milestoneId);
   let resolvedTeamId = teamId;
   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);
@@ -1650,10 +1681,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",
@@ -1662,6 +1696,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({
@@ -1669,14 +1705,17 @@ var updateProjectSchema = z8.object({
   name: z8.string().min(1).optional(),
   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. 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)."
   ),
   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(
@@ -1684,11 +1723,12 @@ var updateProjectSchema = z8.object({
   )
 });
 async function updateProject(input) {
-  const { id, ownerId, teamId, stageId, fields, ...rest } = input;
+  const { id, partyId, ownerId, teamId, stageId, fields, ...rest } = input;
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
+  setRef(body, "party", partyId);
   let resolvedTeamId = teamId;
   let resolvedStageId = stageId;
   if (ownerId !== void 0 && (teamId === void 0 || stageId === void 0)) {
@@ -1698,11 +1738,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",
@@ -1800,15 +1847,33 @@ var updateTaskSchema = z9.object({
   ),
   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."
+  ),
+  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. 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."
+  ),
+  projectId: positiveId.nullable().optional().describe(
+    "Re-link the task to a project (kase) by id, or `null` to orphan it. Mutually exclusive with `partyId` / `opportunityId` \u2014 see `partyId` for the XOR semantic."
   )
 });
 async function updateTask(input) {
-  const { id, ownerId, ...rest } = input;
+  const { id, ownerId, partyId, opportunityId, projectId, ...rest } = input;
+  const setCount = [partyId, opportunityId, projectId].filter((v) => typeof v === "number").length;
+  if (setCount > 1) {
+    throw new Error(
+      "update_task: provide at most one of partyId, opportunityId, or projectId (Capsule rejects multi-parent tasks with 422 'task can be related to at most one entity')"
+    );
+  }
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
   setRef(body, "owner", ownerId);
+  setNullableRef(body, "party", partyId);
+  setNullableRef(body, "opportunity", opportunityId);
+  setNullableRef(body, "kase", projectId);
   return capsulePut(`/tasks/${id}`, { task: body });
 }
 var completeTaskSchema = z9.object({
@@ -2577,7 +2642,7 @@ function createCapsuleMcpServer(opts) {
   const server2 = new McpServer(
     {
       name: "capsulemcp",
-      version: "1.6.2",
+      version: "1.6.5",
       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
@@ -2673,14 +2738,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). 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
     );
@@ -2815,7 +2880,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server2,
       "update_opportunity",
-      "Update fields on an existing opportunity. 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.",
+      "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
     );
@@ -2880,10 +2945,17 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server2,
       "update_project",
-      "Update fields on an existing project. 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.",
+      "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",
@@ -2959,7 +3031,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server2,
       "update_task",
-      "Update fields on an existing task: `description`, `dueOn`, `dueTime`, `detail`, `status` (OPEN or COMPLETED), and `ownerId`. Only the fields you provide are changed. To mark a task done, prefer the dedicated `complete_task` tool \u2014 it's idempotent (a no-op success on an already-completed task) and semantically clearer than `update_task status=COMPLETED`. Capsule rejects directly setting status=PENDING (which exists only internally for track-driven tasks); use OPEN or COMPLETED. Completed tasks remain fully editable \u2014 Capsule does not enforce closed-record immutability.",
+      "Update fields on an existing task: `description`, `dueOn`, `dueTime`, `detail`, `status` (OPEN or COMPLETED), `ownerId`, and the parent-reference fields `partyId`, `opportunityId`, `projectId`. Pass a parent id to re-link the task, or null on a parent field to orphan/unlink it; at most one parent id may be set in a single call, though null+id swaps are allowed. Only the fields you provide are changed. To mark a task done, prefer the dedicated `complete_task` tool \u2014 it's idempotent (a no-op success on an already-completed task) and semantically clearer than `update_task status=COMPLETED`. Capsule rejects directly setting status=PENDING (which exists only internally for track-driven tasks); use OPEN or COMPLETED. Completed tasks remain fully editable \u2014 Capsule does not enforce closed-record immutability.",
       updateTaskSchema,
       updateTask
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capsulemcp",
-  "version": "1.6.2",
+  "version": "1.6.5",
   "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",