capsulemcp 1.0.0

package/dist/index.js

@@ -0,0 +1,2593 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/capsule/client.ts
+import { fetch } from "undici";
+var DEFAULT_BASE_URL = "https://api.capsulecrm.com/api/v2";
+function baseUrl() {
+  const override = process.env["CAPSULE_API_BASE_URL"];
+  if (!override) return DEFAULT_BASE_URL;
+  if (!URL.canParse(override)) {
+    throw new CapsuleAuthError(
+      `CAPSULE_API_BASE_URL is not a valid URL: ${JSON.stringify(override)}`
+    );
+  }
+  const u = new URL(override);
+  const isLocal = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]" || u.hostname === "::1";
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && isLocal)) {
+    throw new CapsuleAuthError(
+      `CAPSULE_API_BASE_URL must be https:// (or http:// on localhost); got ${u.protocol}//${u.hostname}. Sending the Capsule API token to that URL would expose it.`
+    );
+  }
+  return override;
+}
+function isReadOnly() {
+  const v = process.env["CAPSULE_MCP_READONLY"]?.toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+var CapsuleReadOnlyError = class extends Error {
+  constructor(method) {
+    super(
+      `capsulemcp is running in read-only mode (CAPSULE_MCP_READONLY is set). ${method} requests are refused. Unset CAPSULE_MCP_READONLY to enable writes.`
+    );
+    this.name = "CapsuleReadOnlyError";
+  }
+};
+var CapsuleAuthError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CapsuleAuthError";
+  }
+};
+var CapsuleApiError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "CapsuleApiError";
+  }
+  status;
+};
+function getToken() {
+  const token = process.env["CAPSULE_API_TOKEN"];
+  if (!token) {
+    throw new CapsuleAuthError(
+      "CAPSULE_API_TOKEN environment variable is not set. Generate a Personal Access Token via My Preferences \u2192 API Authentication Tokens in Capsule."
+    );
+  }
+  return token;
+}
+function baseHeaders(token) {
+  return {
+    Authorization: `Bearer ${token}`,
+    Accept: "application/json"
+  };
+}
+function parseNextPage(linkHeader) {
+  if (!linkHeader) return void 0;
+  const match = linkHeader.match(/<[^>]*[?&]page=(\d+)[^>]*>;\s*rel="next"/);
+  return match ? parseInt(match[1], 10) : void 0;
+}
+function parseRateLimitDelay(res) {
+  const DEFAULT_MS = 5e3;
+  const MAX_WAIT_MS = 6e4;
+  const resetRaw = res.headers.get("X-RateLimit-Reset");
+  if (resetRaw) {
+    const resetEpochSec = Number(resetRaw);
+    if (Number.isFinite(resetEpochSec) && resetEpochSec > 0) {
+      const delta = resetEpochSec * 1e3 - Date.now();
+      if (delta <= 0) return DEFAULT_MS;
+      return Math.min(delta, MAX_WAIT_MS);
+    }
+  }
+  const retryAfter = res.headers.get("Retry-After");
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+      return Math.min(seconds * 1e3, MAX_WAIT_MS);
+    }
+    const dateMs = Date.parse(retryAfter);
+    if (Number.isFinite(dateMs)) {
+      const delta = dateMs - Date.now();
+      return delta > 0 ? Math.min(delta, MAX_WAIT_MS) : DEFAULT_MS;
+    }
+  }
+  return DEFAULT_MS;
+}
+async function parseErrorBody(res) {
+  try {
+    const body = await res.json();
+    if (body.errors && body.errors.length > 0) {
+      return body.errors.map((e) => {
+        const parts = [e.resource, e.field].filter(Boolean).join(".");
+        return parts ? `${parts}: ${e.message ?? "invalid"}` : e.message ?? "invalid";
+      }).join("; ");
+    }
+    if (body.message) return body.message;
+    return res.statusText;
+  } catch {
+    return res.statusText;
+  }
+}
+var REQUEST_TIMEOUT_MS = 6e4;
+function withTimeout(options) {
+  if (options && options.signal !== void 0) {
+    return { options, cleanup: () => {
+    } };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  timer.unref();
+  return {
+    options: { ...options ?? {}, signal: controller.signal },
+    cleanup: () => clearTimeout(timer)
+  };
+}
+async function mapAbort(p) {
+  try {
+    return await p;
+  } catch (err) {
+    if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
+      throw new CapsuleApiError(
+        504,
+        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
+      );
+    }
+    throw err;
+  }
+}
+async function fetchWithTimeout(url, options) {
+  const { options: opts, cleanup } = withTimeout(options);
+  try {
+    const res = await fetch(url, opts);
+    return { res, cleanup };
+  } catch (err) {
+    cleanup();
+    if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
+      throw new CapsuleApiError(
+        504,
+        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
+      );
+    }
+    throw err;
+  }
+}
+async function doFetch(url, options) {
+  const first = await fetchWithTimeout(url, options);
+  if (first.res.status === 429) {
+    const delay = parseRateLimitDelay(first.res);
+    first.cleanup();
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    const retried = await fetchWithTimeout(url, options);
+    if (retried.res.status === 429) {
+      retried.cleanup();
+      throw new CapsuleApiError(
+        429,
+        "Rate limit exceeded after one retry. Please slow down your requests."
+      );
+    }
+    return retried;
+  }
+  return first;
+}
+async function throwForStatus(res) {
+  if (res.status === 401) {
+    const detail = await parseErrorBody(res);
+    throw new CapsuleAuthError(
+      `Capsule API returned 401 Unauthorized: ${detail}. Check that CAPSULE_API_TOKEN is valid and not expired.`
+    );
+  }
+  if (!res.ok) {
+    const msg = await parseErrorBody(res);
+    throw new CapsuleApiError(res.status, `Capsule API error ${res.status}: ${msg}`);
+  }
+}
+async function handleResponse(res) {
+  await throwForStatus(res);
+  return mapAbort(res.json());
+}
+function buildUrl(path, params) {
+  const url = new URL(`${baseUrl()}${path}`);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  return url.toString();
+}
+async function capsuleGet(path, params) {
+  const token = getToken();
+  const url = buildUrl(path, params);
+  const { res, cleanup } = await doFetch(url, { headers: baseHeaders(token) });
+  try {
+    const data = await handleResponse(res);
+    const nextPage = parseNextPage(res.headers.get("Link"));
+    return { data, nextPage };
+  } finally {
+    cleanup();
+  }
+}
+async function capsulePost(path, body) {
+  if (isReadOnly()) throw new CapsuleReadOnlyError("POST");
+  const token = getToken();
+  const url = buildUrl(path);
+  const { res, cleanup } = await doFetch(url, {
+    method: "POST",
+    headers: { ...baseHeaders(token), "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  try {
+    return await handleResponse(res);
+  } finally {
+    cleanup();
+  }
+}
+async function capsulePostNoContent(path) {
+  if (isReadOnly()) throw new CapsuleReadOnlyError("POST");
+  const token = getToken();
+  const url = buildUrl(path);
+  const { res, cleanup } = await doFetch(url, {
+    method: "POST",
+    headers: baseHeaders(token)
+  });
+  try {
+    if (res.status === 204) return;
+    await throwForStatus(res);
+    await mapAbort(res.text());
+  } finally {
+    cleanup();
+  }
+}
+async function capsuleSearch(path, body, params) {
+  const token = getToken();
+  const url = buildUrl(path, params);
+  const { res, cleanup } = await doFetch(url, {
+    method: "POST",
+    headers: { ...baseHeaders(token), "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  try {
+    const data = await handleResponse(res);
+    const nextPage = parseNextPage(res.headers.get("Link"));
+    return { data, nextPage };
+  } finally {
+    cleanup();
+  }
+}
+async function capsulePut(path, body) {
+  if (isReadOnly()) throw new CapsuleReadOnlyError("PUT");
+  const token = getToken();
+  const url = buildUrl(path);
+  const { res, cleanup } = await doFetch(url, {
+    method: "PUT",
+    headers: { ...baseHeaders(token), "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  try {
+    return await handleResponse(res);
+  } finally {
+    cleanup();
+  }
+}
+async function capsuleGetBinary(path, maxBytes) {
+  const token = getToken();
+  const url = buildUrl(path);
+  const { res, cleanup } = await doFetch(url, { headers: baseHeaders(token) });
+  try {
+    await throwForStatus(res);
+    const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
+    const declared = res.headers.get("Content-Length");
+    const declaredBytes = declared ? Number(declared) : NaN;
+    if (maxBytes !== void 0 && Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
+      if (res.body) await res.body.cancel().catch(() => {
+      });
+      return {
+        contentType,
+        buffer: Buffer.alloc(0),
+        truncated: true,
+        sizeBytes: declaredBytes
+      };
+    }
+    if (maxBytes !== void 0 && res.body) {
+      const reader = res.body.getReader();
+      const chunks = [];
+      let total = 0;
+      let truncated = false;
+      while (true) {
+        const { done, value } = await mapAbort(reader.read());
+        if (done) break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+          truncated = true;
+          await reader.cancel().catch(() => {
+          });
+          break;
+        }
+        chunks.push(value);
+      }
+      if (truncated) {
+        return {
+          contentType,
+          buffer: Buffer.alloc(0),
+          truncated: true,
+          sizeBytes: total
+        };
+      }
+      const buffer2 = Buffer.concat(chunks.map((c) => Buffer.from(c)));
+      return { contentType, buffer: buffer2, sizeBytes: buffer2.length };
+    }
+    const arrayBuffer = await mapAbort(res.arrayBuffer());
+    const buffer = Buffer.from(arrayBuffer);
+    return { contentType, buffer, sizeBytes: buffer.length };
+  } finally {
+    cleanup();
+  }
+}
+async function capsulePostBinary(path, body, contentType, filename) {
+  if (isReadOnly()) throw new CapsuleReadOnlyError("POST");
+  const token = getToken();
+  const url = buildUrl(path);
+  const { res, cleanup } = await doFetch(url, {
+    method: "POST",
+    headers: {
+      ...baseHeaders(token),
+      "Content-Type": contentType,
+      "Content-Length": String(body.length),
+      "X-Attachment-Filename": encodeURIComponent(filename)
+    },
+    body
+  });
+  try {
+    return await handleResponse(res);
+  } finally {
+    cleanup();
+  }
+}
+async function capsuleDelete(path) {
+  if (isReadOnly()) throw new CapsuleReadOnlyError("DELETE");
+  const token = getToken();
+  const url = buildUrl(path);
+  const { res, cleanup } = await doFetch(url, {
+    method: "DELETE",
+    headers: baseHeaders(token)
+  });
+  try {
+    if (res.status === 204) return;
+    await throwForStatus(res);
+    await mapAbort(res.text());
+  } finally {
+    cleanup();
+  }
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/icon.ts
+var ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="capsulemcp">
+  <!-- Stylised diagonal capsule: two halves with a faint highlight stripe.
+       Designed for crisp display down to 16x16. Visually neutral \u2014 does
+       not reproduce any Capsule CRM trademark. -->
+  <defs>
+    <clipPath id="cap">
+      <rect x="2" y="22" width="60" height="20" rx="10" ry="10"
+            transform="rotate(-32 32 32)"/>
+    </clipPath>
+  </defs>
+  <g clip-path="url(#cap)">
+    <rect x="0" y="0" width="32" height="64" fill="#3B82F6"/>
+    <rect x="32" y="0" width="32" height="64" fill="#1E3A8A"/>
+    <rect x="2" y="22" width="60" height="2" fill="rgba(255,255,255,0.35)"
+          transform="rotate(-32 32 32)"/>
+  </g>
+  <rect x="2" y="22" width="60" height="20" rx="10" ry="10"
+        transform="rotate(-32 32 32)" fill="none"
+        stroke="rgba(0,0,0,0.15)" stroke-width="1"/>
+</svg>`;
+var ICON_DATA_URI = `data:image/svg+xml;base64,${Buffer.from(ICON_SVG, "utf8").toString("base64")}`;
+var ICONS = [
+  {
+    src: ICON_DATA_URI,
+    mimeType: "image/svg+xml",
+    sizes: ["64x64", "any"]
+  }
+];
+
+// src/server/register-tool.ts
+function wrapAsText(result) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+  };
+}
+function registerTool(server2, name, description, schema, handler) {
+  const registerWithSchema = server2.registerTool.bind(server2);
+  registerWithSchema(name, { description, inputSchema: schema }, async (input) => {
+    const result = await handler(input);
+    return wrapAsText(result);
+  });
+}
+
+// src/tools/parties.ts
+import { z as z3 } from "zod";
+
+// src/tools/descriptions.ts
+var EMBED_TAGS_FIELDS_DESCRIPTION = "Comma-separated embeds, e.g. 'tags,fields'";
+var EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION = "Comma-separated embeds, e.g. 'attachments,participants'";
+
+// src/tools/confirm-flag.ts
+import { z } from "zod";
+var CONFIRM_REQUIRED_MESSAGE = "confirm: true is required to perform this destructive operation (set the parameter explicitly to acknowledge the destructive intent)";
+function confirmFlag() {
+  return z.literal(true, { error: () => CONFIRM_REQUIRED_MESSAGE });
+}
+
+// src/capsule/idempotent.ts
+var isCapsule404 = (err) => err instanceof CapsuleApiError && err.status === 404;
+var isCapsuleTagNotFound = (err) => err instanceof CapsuleApiError && err.status === 422 && /tag not found/i.test(err.message);
+async function idempotent(op, success, alreadyDone, isAlreadyDoneError = isCapsule404) {
+  try {
+    await op();
+    return success();
+  } catch (err) {
+    if (isAlreadyDoneError(err)) return alreadyDone();
+    throw err;
+  }
+}
+async function idempotentWithResult(op, success, alreadyDone, isAlreadyDoneError = isCapsule404) {
+  try {
+    const result = await op();
+    return success(result);
+  } catch (err) {
+    if (isAlreadyDoneError(err)) return alreadyDone();
+    throw err;
+  }
+}
+
+// src/tools/custom-field-helpers.ts
+import { z as z2 } from "zod";
+var CustomFieldWriteSchema = z2.object({
+  definitionId: z2.number().int().positive().describe(
+    "The custom-field definition id from list_custom_fields. Identifies which field on the entity to set."
+  ),
+  value: z2.union([z2.string(), z2.number(), z2.boolean(), z2.null()]).describe(
+    "The new value. String for TEXT / DATE / LIST / LARGE_TEXT / LINK fields, number for NUMBER fields, boolean for BOOLEAN fields. Clearing: pass null for TEXT / NUMBER / DATE / LIST (Capsule removes the row). BOOLEAN does NOT accept null (Capsule returns 422 'invalid type for field'); use `value: false` instead. Note BOOLEAN fields are observably **two-state**: a row exists with `value: true`, or no row exists. Setting `value: false` removes the row entirely \u2014 readers should treat absent BOOLEAN rows as equivalent to false. Tri-state BOOLEAN semantics (true / false / unknown) are not achievable through Capsule's API. Audit-log noise: sending value=null on a field that's already empty/cleared is accepted by Capsule but still bumps the parent entity's `updatedAt`. Read the current value via embed='fields' first if `updatedAt` is being used as a 'last meaningful change' signal. NUMBER quirks: Capsule stores numerics correctly but the read-back via embed=fields returns them as STRINGS (e.g. value=3 reads as '3'); callers comparing values must coerce. TEXT quirks: value='' has the same observable effect as value=null (row removed); empty-string and never-set are indistinguishable."
+  )
+});
+function fieldsArrayDescriptor(entityToolName) {
+  return `Set custom field values on this record. PARTIAL UPDATE: only the definitions you list are touched; any field NOT in this array is left unchanged. Discover available definitions via list_custom_fields; read current values via ${entityToolName} with embed='fields'.`;
+}
+function mapFieldsForBody(fields) {
+  if (fields === void 0) return void 0;
+  return fields.map((f) => ({
+    definition: { id: f.definitionId },
+    value: f.value
+  }));
+}
+
+// src/tools/parties.ts
+var EmailAddressSchema = z3.object({
+  address: z3.string().email(),
+  type: z3.string().optional()
+});
+var PhoneNumberSchema = z3.object({
+  // Capsule rejects empty strings with `phoneNumber.number: number is
+  // required`. Enforce at the schema layer to catch typos pre-call,
+  // matching how EmailAddressSchema's address field behaves.
+  number: z3.string().min(1),
+  type: z3.string().optional()
+});
+var CountryDescription = "Country name. Capsule validates this against a small canonical-English-name dictionary; inputs not in the dictionary are REJECTED with 422 'address.country: unknown country' (NOT silently passed through or normalised). Probed examples \u2014 accepted: `United States`, `United Kingdom`, `Czechia`, `Germany`. Aliased: `USA \u2192 United States`. Rejected: `United States of America`, `Czech Republic` (use `Czechia`), `UK`/`Britain` (use `United Kingdom`), `Deutschland` (use `Germany`). Empty string is accepted and stored as `null` \u2014 a de-facto 'clear' shape. To discover an accepted name, read an existing party that already has the country set.";
+var AddressSchema = z3.object({
+  street: z3.string().optional(),
+  city: z3.string().optional(),
+  state: z3.string().optional(),
+  country: z3.string().optional().describe(CountryDescription),
+  zip: z3.string().optional()
+});
+function validateWebsiteAddress(data, ctx) {
+  const isUrlService = data.service === void 0 || data.service === "URL";
+  if (!isUrlService) return;
+  if (!URL.canParse(data.address)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["address"],
+      message: "When service is 'URL' (or omitted), address must be a valid URL like 'https://example.com'. For a social handle, set service to the matching type (e.g. service='TWITTER', address='@handle')."
+    });
+    return;
+  }
+  const parsed = new URL(data.address);
+  const BLOCKED = /* @__PURE__ */ new Set(["javascript:", "data:", "vbscript:"]);
+  if (BLOCKED.has(parsed.protocol)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["address"],
+      message: `When service is 'URL', address protocol '${parsed.protocol}' is not allowed. Use http: or https:.`
+    });
+  }
+}
+var WebsiteServiceEnum = z3.enum([
+  "URL",
+  "SKYPE",
+  "TWITTER",
+  "LINKED_IN",
+  "FACEBOOK",
+  "XING",
+  "FEED",
+  "GOOGLE_PLUS",
+  "FLICKR",
+  "GITHUB",
+  "YOUTUBE",
+  "INSTAGRAM",
+  "PINTEREST",
+  "TIKTOK",
+  "THREADS",
+  "BLUESKY",
+  "SNAPCHAT"
+]);
+var WebsiteSchema = z3.object({
+  address: z3.string().min(1).describe(
+    "The website address. A URL when service='URL', or a handle (e.g. '@acmeco') for social services like 'TWITTER', 'INSTAGRAM'. Capsule names this field `address` regardless of service type."
+  ),
+  service: WebsiteServiceEnum.optional().describe(
+    "Service type. One of: URL, SKYPE, TWITTER, LINKED_IN, FACEBOOK, XING, FEED, GOOGLE_PLUS, FLICKR, GITHUB, YOUTUBE, INSTAGRAM, PINTEREST, TIKTOK, THREADS, BLUESKY, SNAPCHAT. Defaults to 'URL' if omitted."
+  )
+}).superRefine(validateWebsiteAddress);
+var searchPartiesSchema = z3.object({
+  q: z3.string().optional().describe("Free-text search query"),
+  embed: z3.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z3.number().int().positive().optional().default(1),
+  perPage: z3.number().int().min(1).max(100).optional().default(25)
+});
+async function searchParties(input) {
+  const path = input.q ? "/parties/search" : "/parties";
+  const { data, nextPage } = await capsuleGet(path, {
+    q: input.q,
+    embed: input.embed,
+    page: input.page,
+    perPage: input.perPage
+  });
+  return { ...data, nextPage };
+}
+var getPartySchema = z3.object({
+  id: z3.number().int().positive().describe("Party ID"),
+  embed: z3.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+});
+async function getParty(input) {
+  const { data } = await capsuleGet(`/parties/${input.id}`, {
+    embed: input.embed
+  });
+  return data;
+}
+var getPartiesSchema = z3.object({
+  ids: z3.array(z3.number().int().positive()).min(1).max(10).describe("Array of party IDs (1\u201310). Capsule caps batch fetches at 10."),
+  embed: z3.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+});
+async function getParties(input) {
+  const { data } = await capsuleGet(`/parties/${input.ids.join(",")}`, {
+    embed: input.embed
+  });
+  return data;
+}
+var listPartyOpportunitiesSchema = z3.object({
+  partyId: z3.number().int().positive(),
+  page: z3.number().int().positive().optional().default(1),
+  perPage: z3.number().int().min(1).max(100).optional().default(25)
+});
+async function listPartyOpportunities(input) {
+  const { data, nextPage } = await capsuleGet(
+    `/parties/${input.partyId}/opportunities`,
+    { page: input.page, perPage: input.perPage }
+  );
+  return { ...data, nextPage };
+}
+var listPartyProjectsSchema = z3.object({
+  partyId: z3.number().int().positive(),
+  page: z3.number().int().positive().optional().default(1),
+  perPage: z3.number().int().min(1).max(100).optional().default(25)
+});
+async function listPartyProjects(input) {
+  const { data, nextPage } = await capsuleGet(
+    `/parties/${input.partyId}/kases`,
+    { page: input.page, perPage: input.perPage }
+  );
+  return { ...data, nextPage };
+}
+var PartyWriteBaseSchema = {
+  about: z3.string().optional(),
+  emailAddresses: z3.array(EmailAddressSchema).optional().describe(
+    "APPEND-ONLY: items are merged into the existing list, never replaced. For atomic add/remove/replace use add_party_email_address and remove_party_email_address_by_id. Passing `[]` here is a silent no-op (does not clear the list and does not advance updatedAt)."
+  ),
+  phoneNumbers: z3.array(PhoneNumberSchema).optional().describe(
+    "APPEND-ONLY: items are merged into the existing list, never replaced. For atomic add/remove/replace use add_party_phone_number and remove_party_phone_number_by_id."
+  ),
+  addresses: z3.array(AddressSchema).optional().describe(
+    "APPEND-ONLY: items are merged into the existing list, never replaced. For atomic add/remove/replace use add_party_address and remove_party_address_by_id. The `country` field is mapped through Capsule's country dictionary \u2014 see `add_party_address.country` for the dictionary edges (small canonical-English-name list; inputs not in the dictionary are REJECTED with 422, not silently dropped)."
+  ),
+  websites: z3.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: z3.number().int().positive().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."
+  )
+};
+var createPartySchema = z3.object({
+  type: z3.enum(["person", "organisation"]),
+  // person
+  firstName: z3.string().optional(),
+  lastName: z3.string().optional(),
+  title: z3.string().optional(),
+  jobTitle: z3.string().optional(),
+  organisationId: z3.number().int().positive().optional().describe("Link person to an existing organisation ID"),
+  // organisation
+  name: z3.string().optional(),
+  ...PartyWriteBaseSchema
+});
+async function createParty(input) {
+  const { ownerId, organisationId, ...rest } = input;
+  const body = { ...rest };
+  if (ownerId) body["owner"] = { id: ownerId };
+  if (organisationId) body["organisation"] = { id: organisationId };
+  return capsulePost("/parties", { party: body });
+}
+var updatePartySchema = z3.object({
+  id: z3.number().int().positive(),
+  firstName: z3.string().optional(),
+  lastName: z3.string().optional(),
+  title: z3.string().optional(),
+  jobTitle: z3.string().optional(),
+  name: z3.string().optional(),
+  fields: z3.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_party")),
+  ...PartyWriteBaseSchema
+});
+async function updateParty(input) {
+  const { id, ownerId, fields, ...rest } = input;
+  const body = {};
+  for (const [k, v] of Object.entries(rest)) {
+    if (v !== void 0) body[k] = v;
+  }
+  if (ownerId) body["owner"] = { id: ownerId };
+  const mappedFields = mapFieldsForBody(fields);
+  if (mappedFields !== void 0) body["fields"] = mappedFields;
+  return capsulePut(`/parties/${id}`, { party: body });
+}
+var deletePartySchema = z3.object({
+  id: z3.number().int().positive(),
+  confirm: confirmFlag().describe(
+    "Must be set to true. Deletes the party AND all linked notes, tasks, opportunities, and projects (kases). Deleting an ORGANISATION does NOT delete people linked to it via organisationId \u2014 their `organisation` field is silently cleared to null and they survive as standalone records. Irreversible."
+  )
+});
+async function deleteParty(input) {
+  if (input.confirm !== true) {
+    throw new Error("delete_party requires confirm: true");
+  }
+  return idempotent(
+    () => capsuleDelete(`/parties/${input.id}`),
+    () => ({ deleted: true, alreadyDeleted: false, id: input.id }),
+    () => ({ deleted: true, alreadyDeleted: true, id: input.id })
+  );
+}
+var addPartyEmailAddressSchema = z3.object({
+  partyId: z3.number().int().positive(),
+  address: z3.string().email(),
+  type: z3.string().optional().describe("Free-form label, e.g. 'Work', 'Home'.")
+});
+async function addPartyEmailAddress(input) {
+  const { partyId, address, type } = input;
+  const item = { address };
+  if (type !== void 0) item["type"] = type;
+  return capsulePut(`/parties/${partyId}`, {
+    party: { emailAddresses: [item] }
+  });
+}
+var removePartyEmailAddressByIdSchema = z3.object({
+  partyId: z3.number().int().positive(),
+  emailAddressId: z3.number().int().positive().describe(
+    "Capsule's id for the email-address row. Read it from get_party (each entry in emailAddresses carries an id)."
+  )
+});
+async function removePartyEmailAddressById(input) {
+  const { partyId, emailAddressId } = input;
+  return idempotentWithResult(
+    () => capsulePut(`/parties/${partyId}`, {
+      party: { emailAddresses: [{ id: emailAddressId, _delete: true }] }
+    }),
+    (result) => ({
+      removed: true,
+      alreadyRemoved: false,
+      partyId,
+      emailAddressId,
+      ...result
+    }),
+    () => ({ removed: true, alreadyRemoved: true, partyId, emailAddressId })
+  );
+}
+var addPartyPhoneNumberSchema = z3.object({
+  partyId: z3.number().int().positive(),
+  number: z3.string().min(1),
+  type: z3.string().optional().describe("Free-form label, e.g. 'Work', 'Mobile'.")
+});
+async function addPartyPhoneNumber(input) {
+  const { partyId, number, type } = input;
+  const item = { number };
+  if (type !== void 0) item["type"] = type;
+  return capsulePut(`/parties/${partyId}`, {
+    party: { phoneNumbers: [item] }
+  });
+}
+var removePartyPhoneNumberByIdSchema = z3.object({
+  partyId: z3.number().int().positive(),
+  phoneNumberId: z3.number().int().positive().describe(
+    "Capsule's id for the phone-number row. Read it from get_party (each entry in phoneNumbers carries an id)."
+  )
+});
+async function removePartyPhoneNumberById(input) {
+  const { partyId, phoneNumberId } = input;
+  return idempotentWithResult(
+    () => capsulePut(`/parties/${partyId}`, {
+      party: { phoneNumbers: [{ id: phoneNumberId, _delete: true }] }
+    }),
+    (result) => ({
+      removed: true,
+      alreadyRemoved: false,
+      partyId,
+      phoneNumberId,
+      ...result
+    }),
+    () => ({ removed: true, alreadyRemoved: true, partyId, phoneNumberId })
+  );
+}
+var addPartyAddressSchema = z3.object({
+  partyId: z3.number().int().positive(),
+  street: z3.string().optional(),
+  city: z3.string().optional(),
+  state: z3.string().optional(),
+  country: z3.string().optional().describe(CountryDescription),
+  zip: z3.string().optional(),
+  type: z3.string().optional().describe("Free-form label, e.g. 'Office', 'Home'.")
+});
+async function addPartyAddress(input) {
+  const { partyId, ...rest } = input;
+  const item = {};
+  for (const [k, v] of Object.entries(rest)) {
+    if (v !== void 0) item[k] = v;
+  }
+  return capsulePut(`/parties/${partyId}`, {
+    party: { addresses: [item] }
+  });
+}
+var removePartyAddressByIdSchema = z3.object({
+  partyId: z3.number().int().positive(),
+  addressId: z3.number().int().positive().describe(
+    "Capsule's id for the address row. Read it from get_party (each entry in addresses carries an id)."
+  )
+});
+async function removePartyAddressById(input) {
+  const { partyId, addressId } = input;
+  return idempotentWithResult(
+    () => capsulePut(`/parties/${partyId}`, {
+      party: { addresses: [{ id: addressId, _delete: true }] }
+    }),
+    (result) => ({
+      removed: true,
+      alreadyRemoved: false,
+      partyId,
+      addressId,
+      ...result
+    }),
+    () => ({ removed: true, alreadyRemoved: true, partyId, addressId })
+  );
+}
+var addPartyWebsiteSchema = z3.object({
+  partyId: z3.number().int().positive(),
+  address: z3.string().min(1).describe(
+    "The website address. A URL when service='URL', or a handle (e.g. '@acmeco') for social services."
+  ),
+  service: WebsiteServiceEnum.optional().describe("Defaults to 'URL' if omitted.")
+}).superRefine(validateWebsiteAddress);
+async function addPartyWebsite(input) {
+  const { partyId, address, service } = input;
+  const item = { address };
+  if (service !== void 0) item["service"] = service;
+  return capsulePut(`/parties/${partyId}`, {
+    party: { websites: [item] }
+  });
+}
+var removePartyWebsiteByIdSchema = z3.object({
+  partyId: z3.number().int().positive(),
+  websiteId: z3.number().int().positive().describe(
+    "Capsule's id for the website row. Read it from get_party (each entry in websites carries an id)."
+  )
+});
+async function removePartyWebsiteById(input) {
+  const { partyId, websiteId } = input;
+  return idempotentWithResult(
+    () => capsulePut(`/parties/${partyId}`, {
+      party: { websites: [{ id: websiteId, _delete: true }] }
+    }),
+    (result) => ({
+      removed: true,
+      alreadyRemoved: false,
+      partyId,
+      websiteId,
+      ...result
+    }),
+    () => ({ removed: true, alreadyRemoved: true, partyId, websiteId })
+  );
+}
+
+// src/tools/opportunities.ts
+import { z as z4 } from "zod";
+var OpportunityValueSchema = z4.object({
+  amount: z4.number().nonnegative(),
+  currency: z4.string({
+    error: (iss) => iss.code === "invalid_type" && iss.input === void 0 ? "currency is required when amount is set (3-letter ISO 4217 code, e.g. 'USD', 'EUR', 'GBP')" : void 0
+  }).length(3).describe(
+    "ISO 4217 currency code (3 letters), e.g. 'GBP', 'USD', 'EUR'. Required when amount is set."
+  )
+});
+var searchOpportunitiesSchema = z4.object({
+  q: z4.string().optional().describe("Free-text search query"),
+  embed: z4.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z4.number().int().positive().optional().default(1),
+  perPage: z4.number().int().min(1).max(100).optional().default(25)
+});
+async function searchOpportunities(input) {
+  const path = input.q ? "/opportunities/search" : "/opportunities";
+  const { data, nextPage } = await capsuleGet(path, {
+    q: input.q,
+    embed: input.embed,
+    page: input.page,
+    perPage: input.perPage
+  });
+  return { ...data, nextPage };
+}
+var getOpportunitySchema = z4.object({
+  id: z4.number().int().positive(),
+  embed: z4.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+});
+async function getOpportunity(input) {
+  const { data } = await capsuleGet(`/opportunities/${input.id}`, {
+    embed: input.embed
+  });
+  return data;
+}
+var getOpportunitiesSchema = z4.object({
+  ids: z4.array(z4.number().int().positive()).min(1).max(10).describe("Array of opportunity IDs (1\u201310). Capsule caps batch fetches at 10."),
+  embed: z4.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+});
+async function getOpportunities(input) {
+  const { data } = await capsuleGet(
+    `/opportunities/${input.ids.join(",")}`,
+    { embed: input.embed }
+  );
+  return data;
+}
+var createOpportunitySchema = z4.object({
+  name: z4.string().min(1),
+  partyId: z4.number().int().positive().describe("ID of the party this opportunity belongs to"),
+  milestoneId: z4.number().int().positive().describe(
+    "ID of the pipeline milestone to place this opportunity at. The milestone implicitly determines the pipeline \u2014 there is no separate pipelineId parameter. Discover via list_pipelines / list_milestones."
+  ),
+  description: z4.string().optional(),
+  value: OpportunityValueSchema.optional(),
+  expectedCloseOn: z4.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  probability: z4.number().int().min(0).max(100).optional(),
+  ownerId: z4.number().int().positive().optional().describe(
+    "Assign to user ID. Defaults to the API-token owner when omitted \u2014 note that opportunities do NOT inherit owner from the linked party, even though one might expect it. Once set, this connector cannot clear the owner back to null (use Capsule's web UI). Discover IDs via list_users."
+  )
+});
+async function createOpportunity(input) {
+  const { partyId, milestoneId, ownerId, ...rest } = input;
+  const body = {
+    ...rest,
+    party: { id: partyId },
+    milestone: { id: milestoneId }
+  };
+  if (ownerId) body["owner"] = { id: ownerId };
+  return capsulePost("/opportunities", { opportunity: body });
+}
+var updateOpportunitySchema = z4.object({
+  id: z4.number().int().positive(),
+  name: z4.string().min(1).optional(),
+  milestoneId: z4.number().int().positive().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."
+  ),
+  description: z4.string().optional(),
+  value: OpportunityValueSchema.optional(),
+  expectedCloseOn: z4.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+  probability: z4.number().int().min(0).max(100).optional().describe(
+    "Win probability 0\u2013100. On an open milestone this overrides the milestone's default probability. CANNOT be set in the same call as a closing milestone (Won/Lost) \u2014 Capsule processes the milestone change first, the opportunity becomes closed, then the probability update is rejected as edit-on-closed-opp with 422 'probability can be updated only for open opportunity'. To close an opportunity, leave probability out of the call: it auto-snaps to 100% (Won) or 0% (Lost)."
+  ),
+  lostReasonId: z4.number().int().positive().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: z4.number().int().positive().optional().describe(
+    "Reassign owner to user ID. Once set, this connector cannot clear an owner back to null \u2014 use Capsule's web UI for that."
+  ),
+  fields: z4.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_opportunity"))
+});
+async function updateOpportunity(input) {
+  const { id, milestoneId, ownerId, lostReasonId, fields, ...rest } = input;
+  const body = {};
+  for (const [k, v] of Object.entries(rest)) {
+    if (v !== void 0) body[k] = v;
+  }
+  if (milestoneId) body["milestone"] = { id: milestoneId };
+  if (ownerId) body["owner"] = { id: ownerId };
+  if (lostReasonId) body["lostReason"] = { id: lostReasonId };
+  const mappedFields = mapFieldsForBody(fields);
+  if (mappedFields !== void 0) body["fields"] = mappedFields;
+  return capsulePut(`/opportunities/${id}`, {
+    opportunity: body
+  });
+}
+var deleteOpportunitySchema = z4.object({
+  id: z4.number().int().positive(),
+  confirm: confirmFlag().describe(
+    "Must be set to true. Permanently deletes the opportunity. Irreversible."
+  )
+});
+async function deleteOpportunity(input) {
+  if (input.confirm !== true) {
+    throw new Error("delete_opportunity requires confirm: true");
+  }
+  return idempotent(
+    () => capsuleDelete(`/opportunities/${input.id}`),
+    () => ({ deleted: true, alreadyDeleted: false, id: input.id }),
+    () => ({ deleted: true, alreadyDeleted: true, id: input.id })
+  );
+}
+
+// src/tools/projects.ts
+import { z as z5 } from "zod";
+var listProjectsSchema = z5.object({
+  status: z5.enum(["OPEN", "CLOSED"]).optional(),
+  embed: z5.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z5.number().int().positive().optional().default(1),
+  perPage: z5.number().int().min(1).max(100).optional().default(25)
+});
+async function listProjects(input) {
+  const { data, nextPage } = await capsuleGet("/kases", {
+    status: input.status,
+    embed: input.embed,
+    page: input.page,
+    perPage: input.perPage
+  });
+  return { ...data, nextPage };
+}
+var getProjectSchema = z5.object({
+  id: z5.number().int().positive(),
+  embed: z5.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+});
+async function getProject(input) {
+  const { data } = await capsuleGet(`/kases/${input.id}`, {
+    embed: input.embed
+  });
+  return data;
+}
+var getProjectsSchema = z5.object({
+  ids: z5.array(z5.number().int().positive()).min(1).max(10).describe("Array of project IDs (1\u201310). Capsule caps batch fetches at 10."),
+  embed: z5.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+});
+async function getProjects(input) {
+  const { data } = await capsuleGet(`/kases/${input.ids.join(",")}`, {
+    embed: input.embed
+  });
+  return data;
+}
+var createProjectSchema = z5.object({
+  name: z5.string().min(1),
+  partyId: z5.number().int().positive().describe("ID of the party linked to this project"),
+  description: z5.string().optional(),
+  status: z5.enum(["OPEN", "CLOSED"]).optional().describe("Defaults to OPEN when omitted."),
+  ownerId: z5.number().int().positive().optional().describe(
+    "Assign to user ID. Defaults to the API-token owner when omitted, same as create_party / create_opportunity / create_task. NOTE: some Capsule tenants configure board-level **automation rules** that mutate `owner` (and `team`) on project creation \u2014 e.g. an automation that clears `owner` when a project enters a particular board. If you observe a project landing with unexpected `owner: null` after a create_project with `ownerId`, check the target board's automation configuration. Capsule's API itself does not drop `ownerId` when `stageId` is also supplied."
+  ),
+  teamId: z5.number().int().positive().optional().describe(
+    "Assign to team ID (discover via list_teams). Capsule projects must always have at least one of {owner, team} set \u2014 Capsule returns 422 'owner or team is required' otherwise. Three ownership shapes are valid: owner alone, team alone, or owner+team (the user must be a member of the team \u2014 users can belong to multiple teams; 422 'owner is not a member of the team' otherwise). Tenant-specific board automations may set the team field on project creation (e.g. 'when project enters board X, set team to T'). If you observe a team set despite omitting `teamId`, check the target board's automation rules."
+  ),
+  stageId: z5.number().int().positive().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: z5.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD")
+});
+async function createProject(input) {
+  const { partyId, ownerId, teamId, status, stageId, ...rest } = input;
+  const body = {
+    ...rest,
+    status: status ?? "OPEN",
+    party: { id: partyId }
+  };
+  if (ownerId) body["owner"] = { id: ownerId };
+  if (teamId) body["team"] = { id: teamId };
+  if (stageId) body["stage"] = stageId;
+  return capsulePost("/kases", { kase: body });
+}
+var updateProjectSchema = z5.object({
+  id: z5.number().int().positive(),
+  name: z5.string().min(1).optional(),
+  description: z5.string().optional(),
+  status: z5.enum(["OPEN", "CLOSED"]).optional(),
+  ownerId: z5.number().int().positive().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: z5.number().int().positive().nullable().optional().describe(
+    "Reassign team: pass a team ID (discover via list_teams) to set, or `null` to unassign. Capsule preserves the existing owner across a team change (server-side), so `update_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: z5.number().int().positive().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."
+  ),
+  expectedCloseOn: z5.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  fields: z5.array(CustomFieldWriteSchema).optional().describe(
+    fieldsArrayDescriptor("get_project") + " 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 updateProject(input) {
+  const { id, ownerId, teamId, stageId, fields, ...rest } = input;
+  const body = {};
+  for (const [k, v] of Object.entries(rest)) {
+    if (v !== void 0) body[k] = v;
+  }
+  let resolvedTeamId = teamId;
+  let resolvedStageId = stageId;
+  if (ownerId !== void 0 && (teamId === void 0 || stageId === void 0)) {
+    const { data } = await capsuleGet(`/kases/${id}`);
+    if (teamId === void 0) {
+      resolvedTeamId = data.kase?.team?.id ?? void 0;
+    }
+    if (stageId === void 0) {
+      resolvedStageId = data.kase?.stage?.id ?? void 0;
+    }
+  }
+  if (ownerId === null) body["owner"] = null;
+  else if (ownerId !== void 0) body["owner"] = { id: ownerId };
+  if (resolvedTeamId === null) body["team"] = null;
+  else if (resolvedTeamId !== void 0) body["team"] = { id: resolvedTeamId };
+  if (resolvedStageId) body["stage"] = resolvedStageId;
+  const mappedFields = mapFieldsForBody(fields);
+  if (mappedFields !== void 0) body["fields"] = mappedFields;
+  return capsulePut(`/kases/${id}`, { kase: body });
+}
+var deleteProjectSchema = z5.object({
+  id: z5.number().int().positive(),
+  confirm: confirmFlag().describe(
+    "Must be set to true. Permanently deletes the project (case). Consider update_project status='CLOSED' instead. Irreversible."
+  )
+});
+async function deleteProject(input) {
+  if (input.confirm !== true) {
+    throw new Error("delete_project requires confirm: true");
+  }
+  return idempotent(
+    () => capsuleDelete(`/kases/${input.id}`),
+    () => ({ deleted: true, alreadyDeleted: false, id: input.id }),
+    () => ({ deleted: true, alreadyDeleted: true, id: input.id })
+  );
+}
+
+// src/tools/tasks.ts
+import { z as z6 } from "zod";
+var listTasksSchema = z6.object({
+  // Note: Capsule has a third internal status `PENDING` (a task that's
+  // part of an active track but not yet "open"), but it can only be
+  // reached via track machinery — it is NOT directly settable by
+  // /tasks PUT, and a list filter for it returns the same as OPEN
+  // anyway. We expose only the two values that are actually filterable
+  // by the v2 API.
+  status: z6.enum(["OPEN", "COMPLETED"]).optional().describe(
+    "Defaults to OPEN when omitted. Pass COMPLETED to filter to completed tasks, or 'OPEN' explicitly."
+  ),
+  ownerId: z6.number().int().positive().optional().describe("Filter to tasks owned by this user ID"),
+  page: z6.number().int().positive().optional().default(1),
+  perPage: z6.number().int().min(1).max(100).optional().default(25)
+});
+async function listTasks(input) {
+  const { data, nextPage } = await capsuleGet("/tasks", {
+    // Default 'OPEN' applied here (not via zod .default()) so that
+    // z.infer keeps `status` optional for callers that omit it.
+    status: input.status ?? "OPEN",
+    // Capsule's owner filter is the bare query param `owner`, not `ownerId`/`assignedToUserId`.
+    owner: input.ownerId,
+    page: input.page,
+    perPage: input.perPage
+  });
+  return { ...data, nextPage };
+}
+var getTaskSchema = z6.object({
+  id: z6.number().int().positive().describe("Task ID")
+});
+async function getTask(input) {
+  const { data } = await capsuleGet(`/tasks/${input.id}`);
+  return data;
+}
+var getTasksSchema = z6.object({
+  ids: z6.array(z6.number().int().positive()).min(1).max(10).describe("Array of task IDs (1\u201310). Capsule caps batch fetches at 10.")
+});
+async function getTasks(input) {
+  const { data } = await capsuleGet(`/tasks/${input.ids.join(",")}`);
+  return data;
+}
+var createTaskSchema = z6.object({
+  description: z6.string().min(1),
+  dueOn: z6.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("YYYY-MM-DD"),
+  dueTime: z6.string().regex(/^\d{2}:\d{2}$/).optional().describe("HH:MM in user's timezone"),
+  detail: z6.string().optional(),
+  ownerId: z6.number().int().positive().optional().describe(
+    "Assign to user ID. 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."
+  ),
+  partyId: z6.number().int().positive().optional().describe("Link task to a party (mutually exclusive with opportunityId/projectId)"),
+  opportunityId: z6.number().int().positive().optional().describe("Link task to an opportunity (mutually exclusive with partyId/projectId)"),
+  projectId: z6.number().int().positive().optional().describe("Link task to a project (mutually exclusive with partyId/opportunityId)")
+});
+async function createTask(input) {
+  const linked = [input.partyId, input.opportunityId, input.projectId].filter(Boolean);
+  if (linked.length > 1) {
+    throw new Error("Provide at most one of partyId, opportunityId, or projectId");
+  }
+  const { ownerId, partyId, opportunityId, projectId, ...rest } = input;
+  const body = { ...rest };
+  if (ownerId) body["owner"] = { id: ownerId };
+  if (partyId) body["party"] = { id: partyId };
+  if (opportunityId) body["opportunity"] = { id: opportunityId };
+  if (projectId) body["kase"] = { id: projectId };
+  return capsulePost("/tasks", { task: body });
+}
+var updateTaskSchema = z6.object({
+  id: z6.number().int().positive(),
+  description: z6.string().min(1).optional(),
+  dueOn: z6.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  dueTime: z6.string().regex(/^\d{2}:\d{2}$/).optional().describe("HH:MM in user's timezone"),
+  detail: z6.string().optional(),
+  // Capsule rejects direct sets of `PENDING` (which is a track-machinery
+  // internal state) with 422 "cannot set task status to PENDING".
+  // Only OPEN and COMPLETED are settable here.
+  status: z6.enum(["OPEN", "COMPLETED"]).optional().describe(
+    "Set to OPEN or COMPLETED. (PENDING exists internally for track-driven tasks but cannot be set directly via this tool \u2014 Capsule rejects it.) Setting status: OPEN on an already-open task is a true no-op (does not advance updatedAt)."
+  ),
+  ownerId: z6.number().int().positive().optional().describe(
+    "Reassign owner to user ID. Once set, this connector cannot clear an owner back to null \u2014 use Capsule's web UI for that."
+  )
+});
+async function updateTask(input) {
+  const { id, ownerId, ...rest } = input;
+  const body = {};
+  for (const [k, v] of Object.entries(rest)) {
+    if (v !== void 0) body[k] = v;
+  }
+  if (ownerId) body["owner"] = { id: ownerId };
+  return capsulePut(`/tasks/${id}`, { task: body });
+}
+var completeTaskSchema = z6.object({
+  id: z6.number().int().positive()
+});
+async function completeTask(input) {
+  return capsulePut(`/tasks/${input.id}`, {
+    task: { status: "COMPLETED" }
+  });
+}
+var deleteTaskSchema = z6.object({
+  id: z6.number().int().positive(),
+  confirm: confirmFlag().describe(
+    "Must be set to true. Permanently deletes the task. To mark done without losing history use complete_task. Irreversible."
+  )
+});
+async function deleteTask(input) {
+  if (input.confirm !== true) {
+    throw new Error("delete_task requires confirm: true");
+  }
+  return idempotent(
+    () => capsuleDelete(`/tasks/${input.id}`),
+    () => ({ deleted: true, alreadyDeleted: false, id: input.id }),
+    () => ({ deleted: true, alreadyDeleted: true, id: input.id })
+  );
+}
+
+// src/tools/entries.ts
+import { z as z7 } from "zod";
+var listEntriesPagination = {
+  page: z7.number().int().positive().optional().default(1),
+  perPage: z7.number().int().min(1).max(100).optional().default(25),
+  embed: z7.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
+};
+var listPartyEntriesSchema = z7.object({
+  partyId: z7.number().int().positive(),
+  ...listEntriesPagination
+});
+async function listPartyEntries(input) {
+  const { data, nextPage } = await capsuleGet(
+    `/parties/${input.partyId}/entries`,
+    { embed: input.embed, page: input.page, perPage: input.perPage }
+  );
+  return { ...data, nextPage };
+}
+var listOpportunityEntriesSchema = z7.object({
+  opportunityId: z7.number().int().positive(),
+  ...listEntriesPagination
+});
+async function listOpportunityEntries(input) {
+  const { data, nextPage } = await capsuleGet(
+    `/opportunities/${input.opportunityId}/entries`,
+    { embed: input.embed, page: input.page, perPage: input.perPage }
+  );
+  return { ...data, nextPage };
+}
+var listProjectEntriesSchema = z7.object({
+  projectId: z7.number().int().positive(),
+  ...listEntriesPagination
+});
+async function listProjectEntries(input) {
+  const { data, nextPage } = await capsuleGet(
+    `/kases/${input.projectId}/entries`,
+    { embed: input.embed, page: input.page, perPage: input.perPage }
+  );
+  return { ...data, nextPage };
+}
+var getEntrySchema = z7.object({
+  id: z7.number().int().positive(),
+  embed: z7.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
+});
+async function getEntry(input) {
+  const { data } = await capsuleGet(`/entries/${input.id}`, {
+    embed: input.embed
+  });
+  return data;
+}
+var listEntriesSchema = z7.object({
+  ...listEntriesPagination
+});
+async function listEntries(input) {
+  const { data, nextPage } = await capsuleGet("/entries", {
+    embed: input.embed,
+    page: input.page,
+    perPage: input.perPage
+  });
+  return { ...data, nextPage };
+}
+var addNoteSchema = z7.object({
+  content: z7.string().min(1).describe(
+    "Note body text. Stored verbatim and treated as MARKDOWN \u2014 Capsule's web UI renders the markdown when displaying. Pass markdown source ('# Heading', '**bold**', '- bullet'), not HTML."
+  ),
+  partyId: z7.number().int().positive().optional().describe("Link note to a party (mutually exclusive with opportunityId/projectId)"),
+  opportunityId: z7.number().int().positive().optional().describe("Link note to an opportunity (mutually exclusive with partyId/projectId)"),
+  projectId: z7.number().int().positive().optional().describe("Link note to a project (mutually exclusive with partyId/opportunityId)"),
+  entryAt: z7.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/).optional().describe(
+    "ISO-8601 timestamp for when this note actually happened (e.g. '2024-03-15T14:30:00Z'). Defaults to now. Use this for backdating historical notes when migrating from another system. `entryAt` is preserved across subsequent update_entry calls; only `updatedAt` advances on edits. Note attribution flows to the API-token owner \u2014 there is no way to record a note as authored by a different user via this connector (a `creatorId` parameter would enable audit-attribution spoofing on shared-connector deployments, so it is intentionally not exposed)."
+  )
+});
+async function addNote(input) {
+  const { content, partyId, opportunityId, projectId, entryAt } = input;
+  const linked = [partyId, opportunityId, projectId].filter(Boolean);
+  if (linked.length !== 1) {
+    throw new Error("Provide exactly one of partyId, opportunityId, or projectId");
+  }
+  const body = { type: "note", content };
+  if (partyId) body["party"] = { id: partyId };
+  if (opportunityId) body["opportunity"] = { id: opportunityId };
+  if (projectId) body["kase"] = { id: projectId };
+  if (entryAt !== void 0) body["entryAt"] = entryAt;
+  return capsulePost("/entries", { entry: body });
+}
+var updateEntrySchema = z7.object({
+  id: z7.number().int().positive().describe("Entry ID to update"),
+  content: z7.string().min(1).optional().describe(
+    "New body text for the entry. For notes, this is the markdown content; for emails, the body. Provide only if you want to change it."
+  ),
+  subject: z7.string().optional().describe(
+    "New subject line. Mostly meaningful on email-type entries; on plain notes Capsule accepts the call (HTTP 200) but **does not store the subject and does not advance `updatedAt`** \u2014 a true no-op for inapplicable fields. `entryAt` (when the note was authored) is preserved across edits; `updatedAt` advances only when an applicable field actually changes. To sort/filter by 'when did this happen', use `entryAt`; for 'last touched', use `updatedAt`."
+  )
+});
+async function updateEntry(input) {
+  const { id, ...rest } = input;
+  const body = {};
+  if (rest.content !== void 0) body["content"] = rest.content;
+  if (rest.subject !== void 0) body["subject"] = rest.subject;
+  if (Object.keys(body).length === 0) {
+    throw new Error("update_entry: provide at least one field to update (content or subject)");
+  }
+  return capsulePut(`/entries/${id}`, { entry: body });
+}
+var deleteEntrySchema = z7.object({
+  id: z7.number().int().positive().describe("Entry (note/email/task-record) ID"),
+  confirm: confirmFlag().describe(
+    "Must be set to true. Permanently deletes the entry \u2014 use this to remove a note from a party/opportunity/project. Irreversible."
+  )
+});
+async function deleteEntry(input) {
+  if (input.confirm !== true) {
+    throw new Error("delete_entry requires confirm: true");
+  }
+  return idempotent(
+    () => capsuleDelete(`/entries/${input.id}`),
+    () => ({ deleted: true, alreadyDeleted: false, id: input.id }),
+    () => ({ deleted: true, alreadyDeleted: true, id: input.id })
+  );
+}
+
+// src/tools/pipelines.ts
+import { z as z8 } from "zod";
+var paginationFields = {
+  page: z8.number().int().positive().optional(),
+  perPage: z8.number().int().min(1).max(100).optional()
+};
+var listPipelinesSchema = z8.object({ ...paginationFields });
+async function listPipelines(input) {
+  const { data, nextPage } = await capsuleGet("/pipelines", {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
+  return { ...data, nextPage };
+}
+var listMilestonesSchema = z8.object({
+  pipelineId: z8.number().int().positive(),
+  ...paginationFields
+});
+async function listMilestones(input) {
+  const { data, nextPage } = await capsuleGet(
+    `/pipelines/${input.pipelineId}/milestones`,
+    { page: input.page ?? 1, perPage: input.perPage ?? 100 }
+  );
+  return { ...data, nextPage };
+}
+
+// src/tools/boards.ts
+import { z as z9 } from "zod";
+var paginationFields2 = {
+  page: z9.number().int().positive().optional(),
+  perPage: z9.number().int().min(1).max(100).optional()
+};
+var listBoardsSchema = z9.object({ ...paginationFields2 });
+async function listBoards(input) {
+  const { data, nextPage } = await capsuleGet("/boards", {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
+  return { ...data, nextPage };
+}
+var listStagesSchema = z9.object({
+  boardId: z9.number().int().positive().optional().describe(
+    "Optional. If provided, returns only the stages defined on that specific board (uses /boards/{id}/stages). Omit to get all stages across all boards in one call."
+  ),
+  ...paginationFields2
+});
+async function listStages(input) {
+  const path = input.boardId !== void 0 ? `/boards/${input.boardId}/stages` : "/stages";
+  const { data, nextPage } = await capsuleGet(path, {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
+  return { ...data, nextPage };
+}
+
+// src/tools/tags.ts
+import { z as z10 } from "zod";
+var TAG_LIST_PATH = {
+  parties: "/parties/tags",
+  opportunities: "/opportunities/tags",
+  kases: "/kases/tags"
+};
+var ENTITY_TO_WRAPPER = {
+  parties: "party",
+  opportunities: "opportunity",
+  kases: "kase"
+};
+var TagEntity = z10.enum(["parties", "opportunities", "kases"]).describe("Which entity type. Use 'kases' for projects (Capsule's legacy path name).");
+var listTagsSchema = z10.object({
+  entity: z10.enum(["parties", "opportunities", "kases"]).describe("The resource type to list tags for"),
+  page: z10.number().int().positive().optional(),
+  perPage: z10.number().int().min(1).max(100).optional()
+});
+async function listTags(input) {
+  const path = TAG_LIST_PATH[input.entity];
+  const { data, nextPage } = await capsuleGet(path, {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
+  return { ...data, nextPage };
+}
+var addTagSchema = z10.object({
+  entity: TagEntity,
+  entityId: z10.number().int().positive().describe("The party/opportunity/kase id."),
+  tagName: z10.string().min(1).describe(
+    "Name of the tag to attach. Capsule resolves by name: if a tag with this name already exists in the tenant it is attached to the entity; if not, Capsule creates the tag and attaches it. Names are tenant-global. Capsule matches case-INSENSITIVELY when resolving (so 'VIP' and 'vip' attach the same tag), preserving the canonical casing from whichever variant was created first. To ensure consistent casing in your tag list, call list_tags first and reuse the exact name from there. Idempotent \u2014 re-attaching an already-attached tag is harmless."
+  )
+});
+async function addTag(input) {
+  const { entity, entityId, tagName } = input;
+  const wrapper = ENTITY_TO_WRAPPER[entity];
+  return capsulePut(`/${entity}/${entityId}`, {
+    [wrapper]: { tags: [{ name: tagName }] }
+  });
+}
+var removeTagByIdSchema = z10.object({
+  entity: TagEntity,
+  entityId: z10.number().int().positive().describe("The party/opportunity/kase id."),
+  tagId: z10.number().int().positive().describe(
+    "The tag's id. Read via get_party / get_opportunity / get_project with embed='tags' \u2014 each tag entry in the response has an `id` field. list_tags returns the same ids for the same tags, so either source works; reading via embed first is the safer pattern because it confirms the tag is actually attached to this entity before you try to remove it (otherwise Capsule returns 422 'tag not found to delete'). Removing detaches the tag from this entity only; the tag definition itself persists in the tenant for other entities that share it."
+  )
+});
+async function removeTagById(input) {
+  const { entity, entityId, tagId } = input;
+  const wrapper = ENTITY_TO_WRAPPER[entity];
+  return idempotentWithResult(
+    () => capsulePut(`/${entity}/${entityId}`, {
+      [wrapper]: { tags: [{ id: tagId, _delete: true }] }
+    }),
+    (result) => ({
+      removed: true,
+      alreadyRemoved: false,
+      entity,
+      entityId,
+      tagId,
+      ...result
+    }),
+    () => ({ removed: true, alreadyRemoved: true, entity, entityId, tagId }),
+    // Tag detach uses PUT with _delete: true and 422s with "tag not
+    // found to delete" on a not-attached tag, instead of the standard
+    // 404. Other 422s with different wording still surface.
+    isCapsuleTagNotFound
+  );
+}
+
+// src/tools/users.ts
+import { z as z11 } from "zod";
+var listUsersSchema = z11.object({
+  page: z11.number().int().positive().optional(),
+  perPage: z11.number().int().min(1).max(100).optional()
+});
+async function listUsers(input) {
+  const { data, nextPage } = await capsuleGet("/users", {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
+  return { ...data, nextPage };
+}
+var getCurrentUserSchema = z11.object({});
+async function getCurrentUser(_input) {
+  const { data } = await capsuleGet("/users/current");
+  return data;
+}
+
+// src/tools/filters.ts
+import { z as z12 } from "zod";
+var FilterConditionSchema = z12.object({
+  field: z12.string().describe(
+    "The Capsule filter-side field name (these differ from response field names \u2014 e.g. response.createdAt is filter-side 'addedOn', response.lastContactedAt is filter-side 'lastContactedOn'). Common: 'addedOn' (date created), 'updatedOn' (date last modified), 'lastContactedOn' (parties only), 'name', 'tag', 'owner', 'team', 'type' (parties: person|organisation), 'milestone' (opportunities), 'status' (opp/project: OPEN|CLOSED), 'closedOn' (opp/project), 'expectedCloseOn' (opp/project), 'hasTags', 'hasEmailAddress' (parties), 'isOpen', 'isStale' (opportunities), 'custom:{fieldId}'. Full per-entity list: https://developer.capsulecrm.com/v2/reference/filters"
+  ),
+  operator: z12.string().describe(
+    "The filter operator. Common: 'is', 'is not' (use value=null to test for null), 'contains', 'does not contain', 'is greater than', 'is less than', 'is within last' (date fields, value=integer days), 'is more than' (date fields, value=integer days ago), 'starts with', 'ends with'. Operator validity depends on the field's type."
+  ),
+  value: z12.union([z12.string(), z12.number(), z12.boolean(), z12.null()]).describe(
+    "The value to compare against. For 'is within last' on date fields, pass an integer number of days. For tag filters, pass the tag name (string) or tag id (number). For 'is not' null tests, pass null literally."
+  )
+});
+var FilterInputSchema = z12.object({
+  conditions: z12.array(FilterConditionSchema).min(1).describe(
+    "Array of filter conditions. All conditions are ANDed together. To get newest records, use a date condition like {field: 'addedOn', operator: 'is within last', value: 7} and pick the highest-id row from the result (Capsule IDs are monotonic)."
+  ),
+  embed: z12.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z12.number().int().positive().optional().default(1),
+  perPage: z12.number().int().min(1).max(100).optional().default(25)
+});
+async function runFilter(entityPath, input) {
+  const { data, nextPage } = await capsuleSearch(
+    `/${entityPath}/filters/results`,
+    { filter: { conditions: input.conditions } },
+    {
+      page: input.page,
+      perPage: input.perPage,
+      embed: input.embed
+    }
+  );
+  return { ...data, nextPage };
+}
+var filterPartiesSchema = FilterInputSchema;
+async function filterParties(input) {
+  return runFilter("parties", input);
+}
+var filterOpportunitiesSchema = FilterInputSchema;
+async function filterOpportunities(input) {
+  return runFilter(
+    "opportunities",
+    input
+  );
+}
+var filterProjectsSchema = FilterInputSchema;
+async function filterProjects(input) {
+  return runFilter("kases", input);
+}
+
+// src/tools/metadata.ts
+import { z as z13 } from "zod";
+var paginationFields3 = {
+  page: z13.number().int().positive().optional(),
+  perPage: z13.number().int().min(1).max(100).optional().describe("Page size, max 100. Defaults to 100 for reference data.")
+};
+var listTeamsSchema = z13.object({ ...paginationFields3 });
+async function listTeams(input) {
+  const { data, nextPage } = await capsuleGet("/teams", {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
+  return { ...data, nextPage };
+}
+var listLostReasonsSchema = z13.object({ ...paginationFields3 });
+async function listLostReasons(input) {
+  const { data, nextPage } = await capsuleGet("/lostreasons", {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
+  return { ...data, nextPage };
+}
+var listActivityTypesSchema = z13.object({ ...paginationFields3 });
+async function listActivityTypes(input) {
+  const { data, nextPage } = await capsuleGet("/activitytypes", {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
+  return { ...data, nextPage };
+}
+var getSiteSchema = z13.object({});
+async function getSite(_input) {
+  const { data } = await capsuleGet("/site");
+  return data;
+}
+var listTrackDefinitionsSchema = z13.object({ ...paginationFields3 });
+async function listTrackDefinitions(input) {
+  const { data, nextPage } = await capsuleGet(
+    "/trackdefinitions",
+    { page: input.page ?? 1, perPage: input.perPage ?? 100 }
+  );
+  return { ...data, nextPage };
+}
+var listCategoriesSchema = z13.object({ ...paginationFields3 });
+async function listCategories(input) {
+  const { data, nextPage } = await capsuleGet("/categories", {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
+  return { ...data, nextPage };
+}
+var listGoalsSchema = z13.object({ ...paginationFields3 });
+async function listGoals(input) {
+  const { data, nextPage } = await capsuleGet("/goals", {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
+  return { ...data, nextPage };
+}
+
+// src/tools/audit.ts
+import { z as z14 } from "zod";
+var listEmployeesSchema = z14.object({
+  partyId: z14.number().int().positive().describe(
+    "The organisation's party id. Returns the people whose `organisation` field links to this party."
+  ),
+  page: z14.number().int().positive().optional().default(1),
+  perPage: z14.number().int().min(1).max(100).optional().default(25),
+  embed: z14.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+});
+async function listEmployees(input) {
+  const { data, nextPage } = await capsuleGet(
+    `/parties/${input.partyId}/people`,
+    { page: input.page, perPage: input.perPage, embed: input.embed }
+  );
+  return { ...data, nextPage };
+}
+var DeletedSinceSchema = z14.string().describe(
+  "REQUIRED. ISO-8601 timestamp; only deletions on or after this point are returned. Example: '2026-01-01T00:00:00Z'."
+);
+var DeletedPagination = {
+  since: DeletedSinceSchema,
+  page: z14.number().int().positive().optional().default(1),
+  perPage: z14.number().int().min(1).max(100).optional().default(25)
+};
+var listDeletedPartiesSchema = z14.object(DeletedPagination);
+async function listDeletedParties(input) {
+  const { data, nextPage } = await capsuleGet("/parties/deleted", {
+    since: input.since,
+    page: input.page,
+    perPage: input.perPage
+  });
+  return { ...data, nextPage };
+}
+var listDeletedOpportunitiesSchema = z14.object(DeletedPagination);
+async function listDeletedOpportunities(input) {
+  const { data, nextPage } = await capsuleGet("/opportunities/deleted", {
+    since: input.since,
+    page: input.page,
+    perPage: input.perPage
+  });
+  return { ...data, nextPage };
+}
+var listDeletedProjectsSchema = z14.object(DeletedPagination);
+async function listDeletedProjects(input) {
+  const { data, nextPage } = await capsuleGet("/kases/deleted", {
+    since: input.since,
+    page: input.page,
+    perPage: input.perPage
+  });
+  return { ...data, nextPage };
+}
+
+// src/tools/relationships.ts
+import { z as z15 } from "zod";
+var RelationshipEntity = z15.enum(["opportunities", "kases"]).describe("Which entity has the additional-party links. Use 'kases' for projects.");
+var listAdditionalPartiesSchema = z15.object({
+  entity: RelationshipEntity,
+  entityId: z15.number().int().positive().describe("ID of the opportunity or project."),
+  embed: z15.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z15.number().int().positive().optional().default(1),
+  perPage: z15.number().int().min(1).max(100).optional().default(25)
+});
+async function listAdditionalParties(input) {
+  const { data, nextPage } = await capsuleGet(
+    `/${input.entity}/${input.entityId}/parties`,
+    { embed: input.embed, page: input.page, perPage: input.perPage }
+  );
+  return { ...data, nextPage };
+}
+var addAdditionalPartySchema = z15.object({
+  entity: RelationshipEntity,
+  entityId: z15.number().int().positive(),
+  partyId: z15.number().int().positive().describe("ID of the party (person or organisation) to link as an additional party.")
+});
+async function addAdditionalParty(input) {
+  try {
+    await capsulePostNoContent(`/${input.entity}/${input.entityId}/parties/${input.partyId}`);
+    return {
+      linked: true,
+      alreadyLinked: false,
+      entity: input.entity,
+      entityId: input.entityId,
+      partyId: input.partyId
+    };
+  } catch (err) {
+    if (err instanceof CapsuleApiError && err.status === 422) {
+      const msg = err.message.toLowerCase();
+      if (msg.includes("already a contact") || msg.includes("already related")) {
+        return {
+          linked: true,
+          alreadyLinked: true,
+          entity: input.entity,
+          entityId: input.entityId,
+          partyId: input.partyId
+        };
+      }
+    }
+    throw err;
+  }
+}
+var removeAdditionalPartySchema = z15.object({
+  entity: RelationshipEntity,
+  entityId: z15.number().int().positive(),
+  partyId: z15.number().int().positive(),
+  confirm: confirmFlag().describe(
+    "Must be set to true. Removes the link between the entity and the additional party. The party itself is not deleted. Reversible by re-adding the link."
+  )
+});
+async function removeAdditionalParty(input) {
+  if (input.confirm !== true) {
+    throw new Error("remove_additional_party requires confirm: true");
+  }
+  return idempotent(
+    () => capsuleDelete(`/${input.entity}/${input.entityId}/parties/${input.partyId}`),
+    () => ({
+      removed: true,
+      alreadyRemoved: false,
+      entity: input.entity,
+      entityId: input.entityId,
+      partyId: input.partyId
+    }),
+    () => ({
+      removed: true,
+      alreadyRemoved: true,
+      entity: input.entity,
+      entityId: input.entityId,
+      partyId: input.partyId
+    })
+  );
+}
+var listAssociatedProjectsSchema = z15.object({
+  opportunityId: z15.number().int().positive(),
+  embed: z15.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z15.number().int().positive().optional().default(1),
+  perPage: z15.number().int().min(1).max(100).optional().default(25)
+});
+async function listAssociatedProjects(input) {
+  const { data, nextPage } = await capsuleGet(
+    `/opportunities/${input.opportunityId}/kases`,
+    { embed: input.embed, page: input.page, perPage: input.perPage }
+  );
+  return { ...data, nextPage };
+}
+
+// src/tools/custom-fields.ts
+import { z as z16 } from "zod";
+var CustomFieldEntity = z16.enum(["parties", "opportunities", "kases"]).describe("Which entity type's custom field schema to inspect. Use 'kases' for projects.");
+var listCustomFieldsSchema = z16.object({
+  entity: CustomFieldEntity
+});
+async function listCustomFields(input) {
+  const { data } = await capsuleGet(
+    `/${input.entity}/fields/definitions`
+  );
+  return data;
+}
+var getCustomFieldSchema = z16.object({
+  entity: CustomFieldEntity,
+  fieldId: z16.number().int().positive().describe("Custom field definition id.")
+});
+async function getCustomField(input) {
+  const { data } = await capsuleGet(
+    `/${input.entity}/fields/definitions/${input.fieldId}`
+  );
+  return data;
+}
+
+// src/tools/tracks.ts
+import { z as z17 } from "zod";
+var TrackEntity = z17.enum(["parties", "opportunities", "kases"]).describe("Use 'kases' for projects.");
+var listEntityTracksSchema = z17.object({
+  entity: TrackEntity,
+  entityId: z17.number().int().positive()
+});
+async function listEntityTracks(input) {
+  const { data } = await capsuleGet(
+    `/${input.entity}/${input.entityId}/tracks`
+  );
+  return data;
+}
+var showTrackSchema = z17.object({
+  trackId: z17.number().int().positive()
+});
+async function showTrack(input) {
+  const { data } = await capsuleGet(`/tracks/${input.trackId}`);
+  return data;
+}
+var applyTrackSchema = z17.object({
+  entity: z17.enum(["opportunities", "kases"]).describe("Which entity to apply the track to. Use 'kases' for projects."),
+  entityId: z17.number().int().positive(),
+  trackDefinitionId: z17.number().int().positive().describe(
+    "The trackDefinition to apply (from list_track_definitions). Auto-creates task definitions on the target entity per the track's rules."
+  ),
+  startDate: z17.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe(
+    "Optional ISO-8601 date (YYYY-MM-DD) the track should start from \u2014 drives task due-date calculations (each task's `dueOn` is computed as startDate + the track-definition's `daysAfter` offset). Defaults to today if omitted. Useful for scheduling a renewal-queue track against a future contract end-date, or backfilling tracks for historical projects."
+  )
+});
+async function applyTrack(input) {
+  const target = input.entity === "opportunities" ? "opportunity" : "kase";
+  const track = {
+    definition: { id: input.trackDefinitionId },
+    [target]: { id: input.entityId }
+  };
+  if (input.startDate !== void 0) track["trackDateOn"] = input.startDate;
+  return capsulePost("/tracks", { track });
+}
+var updateTrackSchema = z17.object({
+  trackId: z17.number().int().positive(),
+  fields: z17.record(z17.string(), z17.unknown()).describe(
+    "Object of fields to update on the track. Capsule's PUT semantics are partial \u2014 only the fields you provide are changed. Common: { complete: true } to mark a track completed. Capsule rejects unknown keys; consult Capsule's docs for the full updatable set."
+  )
+});
+async function updateTrack(input) {
+  if (Object.keys(input.fields).length === 0) {
+    throw new Error("update_track: provide at least one field in `fields`");
+  }
+  return capsulePut(`/tracks/${input.trackId}`, {
+    track: input.fields
+  });
+}
+var removeTrackSchema = z17.object({
+  trackId: z17.number().int().positive(),
+  confirm: confirmFlag().describe(
+    "Must be set to true. Removes the track instance from its entity. **Capsule also deletes the auto-tasks the track created when it was applied** \u2014 they go with the track and become unreachable (404 on GET /tasks/{id}, gone from list_tasks on the parent entity). If you need any of those tasks to outlive the track, copy their content into fresh tasks (or use the web UI) before calling remove_track."
+  )
+});
+async function removeTrack(input) {
+  if (input.confirm !== true) {
+    throw new Error("remove_track requires confirm: true");
+  }
+  return idempotent(
+    () => capsuleDelete(`/tracks/${input.trackId}`),
+    () => ({ removed: true, alreadyRemoved: false, trackId: input.trackId }),
+    () => ({ removed: true, alreadyRemoved: true, trackId: input.trackId })
+  );
+}
+
+// src/tools/attachments.ts
+import { z as z18 } from "zod";
+var DEFAULT_MAX_SIZE_BYTES = 5 * 1024 * 1024;
+var HARD_MAX_SIZE_BYTES = 25 * 1024 * 1024;
+var HARD_MAX_BASE64_CHARS = Math.ceil(HARD_MAX_SIZE_BYTES / 3) * 4;
+var getAttachmentSchema = z18.object({
+  id: z18.number().int().positive().describe("Attachment ID."),
+  maxSizeBytes: z18.number().int().positive().max(HARD_MAX_SIZE_BYTES).optional().describe(
+    `Refuse to return content over this size (default ${DEFAULT_MAX_SIZE_BYTES} bytes \u2248 5MB; max ${HARD_MAX_SIZE_BYTES} bytes \u2248 25MB). Files exceeding the cap return metadata only with a 'truncated: true' flag.`
+  )
+});
+async function getAttachment(input) {
+  const cap = input.maxSizeBytes ?? DEFAULT_MAX_SIZE_BYTES;
+  const { contentType, buffer, truncated, sizeBytes } = await capsuleGetBinary(
+    `/attachments/${input.id}`,
+    cap
+  );
+  if (truncated) {
+    return { contentType, buffer: Buffer.alloc(0), truncated: true, sizeBytes };
+  }
+  return { contentType, buffer, sizeBytes };
+}
+var uploadAttachmentSchema = z18.object({
+  filename: z18.string().min(1).describe(
+    "Filename Capsule should record (e.g. 'contract.pdf'). Capsule does NOT validate consistency between filename, contentType, and the actual bytes \u2014 a typo in either is accepted and the file is stored as labelled."
+  ),
+  contentType: z18.string().min(1).describe(
+    "MIME type of the file (e.g. 'application/pdf', 'image/png', 'text/plain'). Trusted by Capsule verbatim; not cross-checked against `filename` or the actual bytes."
+  ),
+  dataBase64: z18.string().min(1).max(HARD_MAX_BASE64_CHARS).describe(
+    "File contents, base64-encoded. Decoded server-side and uploaded as the request body. Maximum 25 MB per attachment (Capsule's documented limit); the connector rejects oversized base64 before uploading. The inbound HTTP body limit is ~35 MB which leaves room for the base64 expansion of a 25 MB binary."
+  ),
+  content: z18.string().optional().describe(
+    "Body text for the note that will hold the attachment. Defaults to '[attachment]' if omitted."
+  ),
+  partyId: z18.number().int().positive().optional().describe("Link the new note to a party (mutually exclusive with opportunityId / projectId)."),
+  opportunityId: z18.number().int().positive().optional(),
+  projectId: z18.number().int().positive().optional()
+});
+function isValidBase64(s) {
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(s)) return false;
+  const len = s.length;
+  if (len % 4 !== 0) return false;
+  return true;
+}
+function decodedBase64Size(s) {
+  const padding = s.endsWith("==") ? 2 : s.endsWith("=") ? 1 : 0;
+  return s.length / 4 * 3 - padding;
+}
+async function uploadAttachment(input) {
+  const linked = [input.partyId, input.opportunityId, input.projectId].filter(Boolean);
+  if (linked.length !== 1) {
+    throw new Error(
+      "upload_attachment: provide exactly one of partyId, opportunityId, or projectId"
+    );
+  }
+  if (!isValidBase64(input.dataBase64)) {
+    throw new Error(
+      "upload_attachment: dataBase64 is not valid base64 \u2014 Node's tolerant decoder would silently produce corrupt bytes. Verify the encoding (RFC 4648, padded with '=' to a multiple of 4 chars)."
+    );
+  }
+  const decodedBytes = decodedBase64Size(input.dataBase64);
+  if (decodedBytes > HARD_MAX_SIZE_BYTES) {
+    throw new Error(
+      `upload_attachment: decoded file is ${decodedBytes} bytes, exceeding the ${HARD_MAX_SIZE_BYTES} byte attachment limit. Split or shrink the file before uploading.`
+    );
+  }
+  const buffer = Buffer.from(input.dataBase64, "base64");
+  const uploaded = await capsulePostBinary(
+    "/attachments/upload",
+    buffer,
+    input.contentType,
+    input.filename
+  );
+  const token = uploaded.upload.token;
+  const entryBody = {
+    type: "note",
+    content: input.content ?? "[attachment]",
+    attachments: [{ token }]
+  };
+  if (input.partyId) entryBody["party"] = { id: input.partyId };
+  if (input.opportunityId) entryBody["opportunity"] = { id: input.opportunityId };
+  if (input.projectId) entryBody["kase"] = { id: input.projectId };
+  return capsulePost("/entries", { entry: entryBody });
+}
+
+// src/tools/saved-filters.ts
+import { z as z19 } from "zod";
+var EntitySchema = z19.enum(["parties", "opportunities", "kases"]).describe(
+  "Which entity type the filter operates over. Use 'kases' for projects (Capsule's legacy name)."
+);
+var listSavedFiltersSchema = z19.object({
+  entity: EntitySchema
+});
+async function listSavedFilters(input) {
+  const { data } = await capsuleGet(`/${input.entity}/filters`);
+  return data;
+}
+var runSavedFilterSchema = z19.object({
+  entity: EntitySchema,
+  id: z19.number().int().positive().describe("The saved filter id (from list_saved_filters)."),
+  embed: z19.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z19.number().int().positive().optional().default(1),
+  perPage: z19.number().int().min(1).max(100).optional().default(25)
+});
+async function runSavedFilter(input) {
+  const { data, nextPage } = await capsuleGet(
+    `/${input.entity}/filters/${input.id}/results`,
+    { page: input.page, perPage: input.perPage, embed: input.embed }
+  );
+  return { ...data, nextPage };
+}
+
+// src/server.ts
+function createCapsuleMcpServer() {
+  const readOnly = isReadOnly();
+  const server2 = new McpServer({
+    name: "capsulemcp",
+    version: "1.0.0",
+    description: "Read and (optionally) modify Capsule CRM data \u2014 parties, opportunities, projects, tasks, timeline entries, pipelines, tags.",
+    websiteUrl: "https://github.com/soil-dev/capsulemcp",
+    icons: ICONS
+  });
+  registerTool(
+    server2,
+    "search_parties",
+    "Free-text search or list people and organisations in Capsule CRM. Returns results in Capsule's default order (no sort parameter is supported here). For structured queries \u2014 'most recent', 'tagged X', 'added this month' \u2014 use filter_parties instead.",
+    searchPartiesSchema,
+    searchParties
+  );
+  registerTool(
+    server2,
+    "filter_parties",
+    "Filter parties by structured conditions (date ranges, tags, fields). Use this \u2014 not search_parties \u2014 for questions like 'most recent client', 'parties added this week', 'parties tagged VIP'. Capsule's API does not support ad-hoc sort, but for 'most recent X' you can filter by a date field (e.g. {field: 'addedOn', operator: 'is within last', value: 30}) and pick the highest-id row from the result \u2014 Capsule IDs are monotonic, so newest id = newest record.",
+    filterPartiesSchema,
+    filterParties
+  );
+  registerTool(
+    server2,
+    "get_party",
+    "Fetch a single party (person or organisation) by its numeric ID.",
+    getPartySchema,
+    getParty
+  );
+  registerTool(
+    server2,
+    "get_parties",
+    "Batch-fetch up to 10 parties by ID in a single call. Use this when Claude already knows several party IDs to avoid N round trips of get_party.",
+    getPartiesSchema,
+    getParties
+  );
+  registerTool(
+    server2,
+    "list_party_opportunities",
+    "List all opportunities linked to a given party.",
+    listPartyOpportunitiesSchema,
+    listPartyOpportunities
+  );
+  registerTool(
+    server2,
+    "list_party_projects",
+    "List all projects (cases) linked to a given party.",
+    listPartyProjectsSchema,
+    listPartyProjects
+  );
+  registerTool(
+    server2,
+    "list_employees",
+    "List the people who work at a given organisation party. Returns the parties whose `organisation` field references the given partyId. Use this to answer 'who works at X?' rather than enumerating all parties.",
+    listEmployeesSchema,
+    listEmployees
+  );
+  registerTool(
+    server2,
+    "list_custom_fields",
+    "List custom field DEFINITIONS for an entity type (parties, opportunities, or projects/kases). Returns the schema \u2014 name, type, options for list-type fields, etc. \u2014 NOT the values on any specific record. To read values on a record, use get_party / get_opportunity / get_project with embed=fields.",
+    listCustomFieldsSchema,
+    listCustomFields
+  );
+  registerTool(
+    server2,
+    "get_custom_field",
+    "Show a single custom field DEFINITION by id. Use list_custom_fields first to discover field ids.",
+    getCustomFieldSchema,
+    getCustomField
+  );
+  registerTool(
+    server2,
+    "list_deleted_parties",
+    "Audit feature: list parties deleted on or after a given timestamp. The `since` parameter is REQUIRED (Capsule rejects the call without it). Response also includes a `restrictedParties` key \u2014 records the integration user can see were deleted but cannot read fully.",
+    listDeletedPartiesSchema,
+    listDeletedParties
+  );
+  if (!readOnly) {
+    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.",
+      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).",
+      updatePartySchema,
+      updateParty
+    );
+    registerTool(
+      server2,
+      "delete_party",
+      "DESTRUCTIVE & IRREVERSIBLE: permanently delete a party (person or organisation). Cascades to all linked notes, tasks, opportunities, AND projects (kases). Deleting an organisation does NOT delete people linked to it via organisationId \u2014 their `organisation` field is silently cleared to null and they survive as standalone records. TRACK INSTANCES applied to cascaded opportunities/projects are NOT cleaned up either \u2014 they survive as orphan records reachable only by track id via show_track. Use remove_track on each track explicitly before deleting the parent party if orphan accumulation matters (rare in practice \u2014 orphans are unreachable from normal navigation). Requires confirm=true. Always read the party first with get_party and confirm with the user before calling. Idempotent on retry: response is `{deleted: true, alreadyDeleted: false, id}` on a fresh delete or `{deleted: true, alreadyDeleted: true, id}` if the party was already gone (Capsule's 404 is caught internally so reconciliation loops can re-issue safely).",
+      deletePartySchema,
+      deleteParty
+    );
+    registerTool(
+      server2,
+      "add_party_email_address",
+      "Append a single email address to a party. Atomic \u2014 one PUT to Capsule. Use this instead of update_party.emailAddresses when you want to add exactly one entry; the bulk array on update_party is append-only and won't replace.",
+      addPartyEmailAddressSchema,
+      addPartyEmailAddress
+    );
+    registerTool(
+      server2,
+      "remove_party_email_address_by_id",
+      "Remove one email-address entry from a party by its row id. Atomic and reversible \u2014 no `confirm: true` gate (re-add with add_party_email_address). Discover the id via get_party \u2014 each entry in the emailAddresses array carries one. Use this to replace an existing entry: remove the old id, then call add_party_email_address with the new value (any associated server-side metadata on the old row is discarded along with the row). Idempotent on retry: response is `{removed: true, alreadyRemoved: false, partyId, emailAddressId, party}` on a fresh remove (the updated party shape is included) or `{removed: true, alreadyRemoved: true, partyId, emailAddressId}` if the row was already gone (Capsule's 404 is caught).",
+      removePartyEmailAddressByIdSchema,
+      removePartyEmailAddressById
+    );
+    registerTool(
+      server2,
+      "add_party_phone_number",
+      "Append a single phone number to a party. Atomic \u2014 one PUT to Capsule. Use this instead of update_party.phoneNumbers for single-entry adds.",
+      addPartyPhoneNumberSchema,
+      addPartyPhoneNumber
+    );
+    registerTool(
+      server2,
+      "remove_party_phone_number_by_id",
+      "Remove one phone-number entry from a party by its row id. Atomic and reversible \u2014 no `confirm: true` gate (re-add with add_party_phone_number). Discover the id via get_party. Idempotent on retry: response is `{removed: true, alreadyRemoved: false, partyId, phoneNumberId, party}` on a fresh remove or `{removed: true, alreadyRemoved: true, partyId, phoneNumberId}` if the row was already gone.",
+      removePartyPhoneNumberByIdSchema,
+      removePartyPhoneNumberById
+    );
+    registerTool(
+      server2,
+      "add_party_address",
+      "Append a single postal address to a party. Atomic \u2014 one PUT to Capsule. Use this instead of update_party.addresses for single-entry adds.",
+      addPartyAddressSchema,
+      addPartyAddress
+    );
+    registerTool(
+      server2,
+      "remove_party_address_by_id",
+      "Remove one address entry from a party by its row id. Atomic and reversible \u2014 no `confirm: true` gate (re-add with add_party_address). Discover the id via get_party. Idempotent on retry: response is `{removed: true, alreadyRemoved: false, partyId, addressId, party}` on a fresh remove or `{removed: true, alreadyRemoved: true, partyId, addressId}` if the row was already gone.",
+      removePartyAddressByIdSchema,
+      removePartyAddressById
+    );
+    registerTool(
+      server2,
+      "add_party_website",
+      "Append a single website / social handle to a party. Atomic \u2014 one PUT to Capsule. Use this instead of update_party.websites for single-entry adds. The 'address' field is a URL when service='URL' or a handle (e.g. '@acmeco') for social services.",
+      addPartyWebsiteSchema,
+      addPartyWebsite
+    );
+    registerTool(
+      server2,
+      "remove_party_website_by_id",
+      "Remove one website entry from a party by its row id. Atomic and reversible \u2014 no `confirm: true` gate (re-add with add_party_website). Discover the id via get_party. Idempotent on retry: response is `{removed: true, alreadyRemoved: false, partyId, websiteId, party}` on a fresh remove or `{removed: true, alreadyRemoved: true, partyId, websiteId}` if the row was already gone.",
+      removePartyWebsiteByIdSchema,
+      removePartyWebsiteById
+    );
+  }
+  registerTool(
+    server2,
+    "search_opportunities",
+    "Free-text search or list opportunities in Capsule CRM. Returns results in Capsule's default order (no sort parameter is supported here). For structured queries \u2014 'most recent', 'won this quarter', 'in pipeline X at milestone Y' \u2014 use filter_opportunities instead.",
+    searchOpportunitiesSchema,
+    searchOpportunities
+  );
+  registerTool(
+    server2,
+    "filter_opportunities",
+    "Filter opportunities by structured conditions (milestone, value, close date, tags). Use this \u2014 not search_opportunities \u2014 for questions like 'last won deal', 'opportunities closed this month', 'pipeline X at milestone Y'. Capsule's API does not support ad-hoc sort, but for 'most recent X' you can filter by a date field (e.g. {field: 'closedOn', operator: 'is within last', value: 90}) and pick the highest-id row \u2014 Capsule IDs are monotonic, so newest id = newest record.",
+    filterOpportunitiesSchema,
+    filterOpportunities
+  );
+  registerTool(
+    server2,
+    "get_opportunity",
+    "Fetch a single opportunity by its numeric ID.",
+    getOpportunitySchema,
+    getOpportunity
+  );
+  registerTool(
+    server2,
+    "get_opportunities",
+    "Batch-fetch up to 10 opportunities by ID in a single call.",
+    getOpportunitiesSchema,
+    getOpportunities
+  );
+  registerTool(
+    server2,
+    "list_deleted_opportunities",
+    "Audit feature: list opportunities deleted on or after a given timestamp. The `since` parameter is REQUIRED. Response also includes a `restrictedOpportunities` key for records the integration user can't read fully.",
+    listDeletedOpportunitiesSchema,
+    listDeletedOpportunities
+  );
+  registerTool(
+    server2,
+    "list_additional_parties",
+    "List secondary party links on an opportunity or project. The 'main' party is on the entity itself (opportunity.party); additional parties are e.g. partners, consultants, or referrers also involved in the deal. Set entity to 'opportunities' or 'kases' (Capsule's term for projects).",
+    listAdditionalPartiesSchema,
+    listAdditionalParties
+  );
+  registerTool(
+    server2,
+    "list_associated_projects",
+    "List projects (cases) associated with a given opportunity. The inverse direction (project \u2192 opportunity) is on each project's `opportunity` field directly.",
+    listAssociatedProjectsSchema,
+    listAssociatedProjects
+  );
+  if (!readOnly) {
+    registerTool(
+      server2,
+      "create_opportunity",
+      "Create a new opportunity linked to a party and a pipeline milestone.",
+      createOpportunitySchema,
+      createOpportunity
+    );
+    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.",
+      updateOpportunitySchema,
+      updateOpportunity
+    );
+    registerTool(
+      server2,
+      "delete_opportunity",
+      "DESTRUCTIVE & IRREVERSIBLE: permanently delete an opportunity. Requires confirm=true. Always read the opportunity first with get_opportunity and confirm with the user before calling. Idempotent on retry: response is `{deleted: true, alreadyDeleted: false, id}` on a fresh delete or `{deleted: true, alreadyDeleted: true, id}` if the opportunity was already gone.",
+      deleteOpportunitySchema,
+      deleteOpportunity
+    );
+  }
+  registerTool(
+    server2,
+    "list_projects",
+    "List projects (cases) in Capsule CRM, optionally filtered by status. Returns results in Capsule's default order (no sort parameter is supported here). For structured queries \u2014 'most recent project', 'projects opened this month', 'projects tagged X' \u2014 use filter_projects instead.",
+    listProjectsSchema,
+    listProjects
+  );
+  registerTool(
+    server2,
+    "filter_projects",
+    "Filter projects (cases) by structured conditions (date ranges, status, tags, owner). Use this \u2014 not list_projects \u2014 for questions like 'most recent project', 'projects opened this month'. Capsule's API does not support ad-hoc sort, but for 'most recent X' you can filter by a date field and pick the highest-id row \u2014 Capsule IDs are monotonic, so newest id = newest record.",
+    filterProjectsSchema,
+    filterProjects
+  );
+  registerTool(
+    server2,
+    "get_project",
+    "Fetch a single project (case) by its numeric ID.",
+    getProjectSchema,
+    getProject
+  );
+  registerTool(
+    server2,
+    "get_projects",
+    "Batch-fetch up to 10 projects (cases) by ID in a single call.",
+    getProjectsSchema,
+    getProjects
+  );
+  registerTool(
+    server2,
+    "list_deleted_projects",
+    "Audit feature: list projects deleted on or after a given timestamp. The `since` parameter is REQUIRED. Response also includes a `restrictedKases` key for records the integration user can't read fully.",
+    listDeletedProjectsSchema,
+    listDeletedProjects
+  );
+  if (!readOnly) {
+    registerTool(
+      server2,
+      "create_project",
+      "Create a new project (case) in Capsule CRM linked to a party.",
+      createProjectSchema,
+      createProject
+    );
+    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.",
+      updateProjectSchema,
+      updateProject
+    );
+    registerTool(
+      server2,
+      "delete_project",
+      "DESTRUCTIVE & IRREVERSIBLE: permanently delete a project (case). Prefer update_project with status='CLOSED' to close a project while preserving history. Requires confirm=true. Always read the project first with get_project and confirm with the user before calling. Idempotent on retry: response is `{deleted: true, alreadyDeleted: false, id}` on a fresh delete or `{deleted: true, alreadyDeleted: true, id}` if the project was already gone.",
+      deleteProjectSchema,
+      deleteProject
+    );
+    registerTool(
+      server2,
+      "add_additional_party",
+      "Link an existing party as an additional (secondary) party on an opportunity or project. The 'main' party is set via update_opportunity / update_project; this adds *additional* parties beyond the main one. Idempotent \u2014 re-adding a linked party is harmless. Response: `{linked: true, alreadyLinked: false}` on a fresh link, `{linked: true, alreadyLinked: true}` if the party was already linked (Capsule's 422 'already a contact' / 'already related' is caught internally and converted).",
+      addAdditionalPartySchema,
+      addAdditionalParty
+    );
+    registerTool(
+      server2,
+      "remove_additional_party",
+      "Remove an additional-party link between an opportunity/project and a party. The party itself is NOT deleted. Requires confirm=true. Reversible by re-adding via add_additional_party. Idempotent on retry: response is `{removed: true, alreadyRemoved: false, entity, entityId, partyId}` on a fresh remove or `{removed: true, alreadyRemoved: true, ...}` if the link was already gone (Capsule's 404 is caught and converted).",
+      removeAdditionalPartySchema,
+      removeAdditionalParty
+    );
+    registerTool(
+      server2,
+      "apply_track",
+      "Apply a track definition to an opportunity or project. Creates a track instance and auto-creates tasks per the track's task definitions; tasks' `dueOn` is computed from `startDate` (defaults to today) plus each task's `daysAfter` offset. Use list_track_definitions to discover available templates. NOT IDEMPOTENT \u2014 applying the same trackDefinitionId twice creates two independent track instances and two sets of auto-tasks (no de-duplication). If you want to apply only once, call list_entity_tracks first and check for an existing instance with the same trackDefinition.id (but mind that list_entity_tracks can include auto-applied tracks from board stage rules, not just manual applies).",
+      applyTrackSchema,
+      applyTrack
+    );
+    registerTool(
+      server2,
+      "update_track",
+      "Update a track instance. Capsule's PUT semantics are partial \u2014 provide only the fields you want to change in `fields`. Common: { complete: true } to mark a track completed.",
+      updateTrackSchema,
+      updateTrack
+    );
+    registerTool(
+      server2,
+      "remove_track",
+      "Remove a track instance from its entity. Capsule also deletes the auto-tasks the track created when it was applied; copy any task details you need before removing the track. Requires confirm=true. Idempotent on retry: response is `{removed: true, alreadyRemoved: false, trackId}` on a fresh remove or `{removed: true, alreadyRemoved: true, trackId}` if the track was already gone.",
+      removeTrackSchema,
+      removeTrack
+    );
+  }
+  registerTool(
+    server2,
+    "list_tasks",
+    "List tasks in Capsule CRM. Defaults to OPEN tasks; pass status to broaden. Optionally filter to a specific owner via ownerId. Capsule does not expose a due-date filter on this endpoint \u2014 for that use filter_* tools elsewhere or iterate.",
+    listTasksSchema,
+    listTasks
+  );
+  registerTool(
+    server2,
+    "get_task",
+    "Fetch a single task by its numeric ID.",
+    getTaskSchema,
+    getTask
+  );
+  registerTool(
+    server2,
+    "get_tasks",
+    "Batch-fetch up to 10 tasks by ID in a single call.",
+    getTasksSchema,
+    getTasks
+  );
+  if (!readOnly) {
+    registerTool(
+      server2,
+      "create_task",
+      "Create a new task, optionally linked to a party, opportunity, or project. Pass at most ONE of partyId / opportunityId / projectId \u2014 the connector rejects multi-target inputs before the HTTP call. Omitting all three is also valid: Capsule creates the task as a STANDALONE task (no parent link), useful for personal reminders or workflow tasks that aren't tied to a specific CRM record.",
+      createTaskSchema,
+      createTask
+    );
+    registerTool(
+      server2,
+      "update_task",
+      "Update fields on an existing task. Only the fields you provide are changed. To mark a task done prefer complete_task.",
+      updateTaskSchema,
+      updateTask
+    );
+    registerTool(
+      server2,
+      "complete_task",
+      "Mark a task as done / completed / finished. Sets status=COMPLETED on the task, populating completedBy and completedAt while preserving the task in history (unlike delete_task which removes it permanently). Use this whenever a user says 'mark done', 'complete', 'finish', or similar \u2014 equivalent to update_task with status:COMPLETED but more discoverable.",
+      completeTaskSchema,
+      completeTask
+    );
+    registerTool(
+      server2,
+      "delete_task",
+      "DESTRUCTIVE & IRREVERSIBLE: permanently delete a task. Prefer complete_task to mark a task done while keeping it in history. Requires confirm=true. Idempotent on retry: response is `{deleted: true, alreadyDeleted: false, id}` on a fresh delete or `{deleted: true, alreadyDeleted: true, id}` if the task was already gone.",
+      deleteTaskSchema,
+      deleteTask
+    );
+  }
+  registerTool(
+    server2,
+    "list_party_entries",
+    "List timeline entries (notes, captured emails, completed-task records) for a party. Use this to read the conversation history with a contact or organisation.",
+    listPartyEntriesSchema,
+    listPartyEntries
+  );
+  registerTool(
+    server2,
+    "list_opportunity_entries",
+    "List timeline entries (notes, captured emails, completed-task records) for an opportunity.",
+    listOpportunityEntriesSchema,
+    listOpportunityEntries
+  );
+  registerTool(
+    server2,
+    "list_project_entries",
+    "List timeline entries (notes, captured emails, completed-task records) for a project (case).",
+    listProjectEntriesSchema,
+    listProjectEntries
+  );
+  registerTool(
+    server2,
+    "get_entry",
+    "Fetch a single timeline entry by its numeric ID. Returns full content (note body, email subject + body, etc.).",
+    getEntrySchema,
+    getEntry
+  );
+  registerTool(
+    server2,
+    "list_entries",
+    "Global timeline feed: every note, captured email, and completed-task record across the whole Capsule account, paginated. Default order is most-recent-first. Use this for 'what activity happened today/this week across the company?' rather than iterating list_party_entries / list_opportunity_entries / list_project_entries.",
+    listEntriesSchema,
+    listEntries
+  );
+  server2.tool(
+    "get_attachment",
+    "Download an attachment by id. Returns image content for image/* types (Claude can describe it natively); decoded text for text/* and application/json (small files); JSON metadata + base64 payload for other binary types (PDF, Office docs, etc.). Files exceeding maxSizeBytes (default 5MB) return metadata only with a `truncated: true` flag.",
+    getAttachmentSchema.shape,
+    async (input) => {
+      const result = await getAttachment(input);
+      if (result.truncated) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  id: input.id,
+                  contentType: result.contentType,
+                  sizeBytes: result.sizeBytes,
+                  truncated: true,
+                  message: `File exceeds the size cap (${input.maxSizeBytes ?? "default"} bytes). Increase maxSizeBytes if you need the bytes; max is 25MB.`
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      }
+      const baseType = result.contentType.split(";")[0].trim().toLowerCase();
+      if (baseType.startsWith("image/")) {
+        return {
+          content: [
+            {
+              type: "image",
+              data: result.buffer.toString("base64"),
+              mimeType: result.contentType
+            }
+          ]
+        };
+      }
+      const isText = baseType.startsWith("text/") || baseType === "application/json" || baseType === "application/xml";
+      if (isText) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  id: input.id,
+                  contentType: result.contentType,
+                  sizeBytes: result.sizeBytes
+                },
+                null,
+                2
+              )
+            },
+            { type: "text", text: result.buffer.toString("utf8") }
+          ]
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                id: input.id,
+                contentType: result.contentType,
+                sizeBytes: result.sizeBytes,
+                base64: result.buffer.toString("base64")
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+  if (!readOnly) {
+    registerTool(
+      server2,
+      "add_note",
+      "Add a note to a party, opportunity, or project. Provide exactly one of partyId, opportunityId, or projectId. The note is always attributed to the API-token owner \u2014 there is no override for the author (a `creatorId` parameter would enable audit-attribution spoofing on shared-connector deployments, so it is intentionally not exposed). Optional `entryAt` lets you backdate the note's authored-at timestamp for legitimate historical-import workflows.",
+      addNoteSchema,
+      addNote
+    );
+    registerTool(
+      server2,
+      "update_entry",
+      "Edit an existing timeline entry \u2014 typically a note. Provide the entry id plus the fields you want to change (content, subject). Only the fields you supply are modified; other fields keep their current values. Cannot change the entry's type. Use this to correct or extend a note added previously.",
+      updateEntrySchema,
+      updateEntry
+    );
+    registerTool(
+      server2,
+      "upload_attachment",
+      "Upload a file as a new note attachment, linked to a party, opportunity, or project. Provide the file as base64-encoded `dataBase64` along with `filename` and `contentType` (MIME). Also provide exactly one of partyId / opportunityId / projectId to anchor the note. Optionally pass `content` to set the note body (defaults to '[attachment]'). Two-step orchestration server-side: bytes upload \u2192 token \u2192 note creation. Adding to an existing entry is not supported.",
+      uploadAttachmentSchema,
+      uploadAttachment
+    );
+    registerTool(
+      server2,
+      "delete_entry",
+      "DESTRUCTIVE & IRREVERSIBLE: permanently delete a note (or other entry) by its ID. Requires confirm=true. Idempotent on retry: response is `{deleted: true, alreadyDeleted: false, id}` on a fresh delete or `{deleted: true, alreadyDeleted: true, id}` if the entry was already gone.",
+      deleteEntrySchema,
+      deleteEntry
+    );
+  }
+  registerTool(
+    server2,
+    "list_pipelines",
+    "List all sales pipelines defined in Capsule CRM.",
+    listPipelinesSchema,
+    listPipelines
+  );
+  registerTool(
+    server2,
+    "list_milestones",
+    "List all milestones (stages) within a specific opportunity pipeline.",
+    listMilestonesSchema,
+    listMilestones
+  );
+  registerTool(
+    server2,
+    "list_boards",
+    "List all project (kase) boards defined in Capsule. A board is a grouping of stages that projects flow through \u2014 the project equivalent of an opportunity pipeline.",
+    listBoardsSchema,
+    listBoards
+  );
+  registerTool(
+    server2,
+    "list_stages",
+    "List project stages. Without arguments returns every stage across every board (each carries a .board reference). Pass boardId to scope to one specific board.",
+    listStagesSchema,
+    listStages
+  );
+  registerTool(
+    server2,
+    "list_teams",
+    "List all teams configured in the Capsule account. Useful as input for filter_* queries that scope by team, and for reporting. LIMITATION: returns team identity only (id, name, description, timestamps). Capsule's v2 API does not expose team\u2194user membership through any endpoint \u2014 `GET /teams/{id}/users` 404s, `embed=users` is silently ignored, and `GET /users/{id}` doesn't include a `teams` field. To determine whether a given user belongs to a given team, either check Capsule's web UI Team Membership page, or probe via `update_project { ownerId: U, teamId: T }` and read the response \u2014 422 'owner is not a member of the team' means U \u2209 T.",
+    listTeamsSchema,
+    listTeams
+  );
+  registerTool(
+    server2,
+    "list_lostreasons",
+    "List all configured opportunity-loss reasons (e.g. 'Poor Qualification', 'Lost to competitor'). Useful for analysing closed-lost opportunities by reason.",
+    listLostReasonsSchema,
+    listLostReasons
+  );
+  registerTool(
+    server2,
+    "list_activitytypes",
+    "List all configured activity types (e.g. Call, Meeting, Email). These are the categories used when logging timeline entries.",
+    listActivityTypesSchema,
+    listActivityTypes
+  );
+  registerTool(
+    server2,
+    "list_categories",
+    "List configured entry/task categories (Call, Email, Meeting, Follow-up, etc.) with their colours. Used to label and filter timeline entries and tasks.",
+    listCategoriesSchema,
+    listCategories
+  );
+  registerTool(
+    server2,
+    "list_track_definitions",
+    "List workflow track definitions: reusable templates that auto-create tasks at configured intervals when applied to an opportunity or project. Each track includes nested taskDefinitions specifying what to create and when. Use this to understand what automations exist.",
+    listTrackDefinitionsSchema,
+    listTrackDefinitions
+  );
+  registerTool(
+    server2,
+    "list_entity_tracks",
+    "List track INSTANCES on a specific record \u2014 i.e., which tracks have been applied to this opportunity / project / party. Distinct from list_track_definitions, which lists the templates. NOTE: some boards have stage-triggered automation that auto-applies tracks when an entity enters specific stages \u2014 tracks returned here may include BOTH manually-applied tracks (via apply_track) and auto-applied tracks from Capsule board rules. To distinguish, compare each track's `trackDefinition.id` against your application's apply_track call history.",
+    listEntityTracksSchema,
+    listEntityTracks
+  );
+  registerTool(
+    server2,
+    "show_track",
+    "Fetch a single track instance by id. Returns the minimal Capsule projection: id, description, trackDateOn, direction, and the array of tasks attached to the track. Capsule's GET /tracks/{id} does NOT include a trackDefinition link, an entity reference, or a completion field \u2014 to find the entity a track is applied to, use list_entity_tracks (which lists track instances by their parent entity); to check completion, the track-tasks' own statuses are the proxy.",
+    showTrackSchema,
+    showTrack
+  );
+  registerTool(
+    server2,
+    "list_goals",
+    "List sales / activity goals configured in the account (per-user or per-team revenue or activity targets). Returns an empty list for accounts that don't use the Goals feature.",
+    listGoalsSchema,
+    listGoals
+  );
+  registerTool(
+    server2,
+    "get_site",
+    "Return the Capsule account this connector is currently authenticated against (subdomain, display name, URL). Diagnostic for 'which Capsule account is this?'. For the PAT owner's user identity, use get_current_user.",
+    getSiteSchema,
+    getSite
+  );
+  registerTool(
+    server2,
+    "list_saved_filters",
+    "List all filters that users have saved in Capsule's web UI for an entity type. Saved filters are reusable \u2014 they bundle conditions, columns, and (importantly) sort. Use this to discover what queries are already configured before building a one-off filter_* call.",
+    listSavedFiltersSchema,
+    listSavedFilters
+  );
+  registerTool(
+    server2,
+    "run_saved_filter",
+    "Run a saved filter by id and return its results, paginated. Unlike filter_parties / filter_opportunities / filter_projects (which use the ad-hoc filter endpoint and CANNOT sort), saved filters DO support sort \u2014 the orderBy is configured in Capsule's web UI when the filter is created. So 'most recent X by Y' questions are answerable in one call IF a saved filter exists; use list_saved_filters first to find one.",
+    runSavedFilterSchema,
+    runSavedFilter
+  );
+  registerTool(
+    server2,
+    "list_tags",
+    "List all tags available for a given entity type (parties, opportunities, or kases).",
+    listTagsSchema,
+    listTags
+  );
+  if (!readOnly) {
+    registerTool(
+      server2,
+      "add_tag",
+      "Attach a tag to a party, opportunity, or project (kase) by NAME. Capsule resolves to an existing tag in the tenant or creates a fresh one with this name. Matching is case-insensitive \u2014 'VIP' and 'vip' attach the same tag, preserving the canonical casing from whichever variant was created first. To avoid creating a genuinely-distinct near-duplicate (e.g. 'VIP' vs 'V.I.P.'), call list_tags first and reuse the exact name. Idempotent \u2014 re-attaching an already-attached tag is harmless. To DETACH a tag, use remove_tag_by_id with the tag's id (read via get_party/get_opportunity/get_project with embed='tags').",
+      addTagSchema,
+      addTag
+    );
+    registerTool(
+      server2,
+      "remove_tag_by_id",
+      "Detach a tag from a party, opportunity, or project (kase). Atomic \u2014 one PUT to Capsule. Reversible \u2014 no `confirm: true` gate (re-attach with add_tag using the same tag name). The `tagId` parameter is the tag's id, readable via get_party/get_opportunity/get_project with embed='tags' (list_tags returns the same ids and also works, but reading via embed first confirms the tag is actually attached to this entity). The tag definition itself remains in the tenant for other entities that still share it. Idempotent on retry: response is `{removed: true, alreadyRemoved: false, entity, entityId, tagId, ...<updated entity>}` on a fresh detach or `{removed: true, alreadyRemoved: true, entity, entityId, tagId}` if the tag was already detached (Capsule's 422 'tag not found to delete' is caught and converted).",
+      removeTagByIdSchema,
+      removeTagById
+    );
+  }
+  registerTool(
+    server2,
+    "list_users",
+    "List all users in the Capsule account.",
+    listUsersSchema,
+    listUsers
+  );
+  registerTool(
+    server2,
+    "get_current_user",
+    "Show the user owning the API token this connector is using. Useful for audit ('under whose Capsule identity is the connector running?') and for confirming a token rotation moved ownership to the expected account. Wraps Capsule's GET /users/current \u2014 note the endpoint is /users/current, not /users/me.",
+    getCurrentUserSchema,
+    getCurrentUser
+  );
+  return server2;
+}
+
+// src/index.ts
+if (!process.env["CAPSULE_API_TOKEN"]) {
+  console.error(
+    "[capsulemcp] CAPSULE_API_TOKEN environment variable is not set. Generate a Personal Access Token via My Preferences \u2192 API Authentication Tokens in Capsule."
+  );
+  process.exit(1);
+}
+var server = createCapsuleMcpServer();
+var transport = new StdioServerTransport();
+if (isReadOnly()) {
+  console.error("[capsulemcp] read-only mode: write/delete tools are not registered");
+}
+try {
+  await server.connect(transport);
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`[capsulemcp] Failed to start: ${message}`);
+  process.exit(1);
+}