capsulemcp 1.7.0 → 1.8.0

package/README.md

@@ -48,7 +48,7 @@ For most individual users the install is a single JSON snippet pasted into Claud
 
 3. Restart Claude Desktop. The Capsule tools appear in the tool picker.
 
-That's it. The first launch fetches the package from npm (a few seconds); subsequent launches are instant from the npx cache. To pin a specific version, use `"capsulemcp@1.7.0"` in `args`. If you're tracking a fork or an unreleased branch, use the GitHub-ref form instead: `"github:soil-dev/capsulemcp#v1.7.0"` — same arguments, just installs from a git clone rather than the npm registry. See [INSTALL.md](INSTALL.md) for the Claude Code path, manual install, and troubleshooting.
+That's it. The first launch fetches the package from npm (a few seconds); subsequent launches are instant from the npx cache. To pin a specific version, use `"capsulemcp@1.8.0"` in `args`. If you're tracking a fork or an unreleased branch, use the GitHub-ref form instead: `"github:soil-dev/capsulemcp#v1.8.0"` — same arguments, just installs from a git clone rather than the npm registry. See [INSTALL.md](INSTALL.md) for the Claude Code path, manual install, and troubleshooting.
 
 ## Tools
 

package/dist/http.js

@@ -26,6 +26,22 @@ var chainHandlers = {
   "capsule.request": (ctx) => {
     ctx.capsuleCalls += 1;
   },
+  // A timed-out or connection-failed call is still an attempt that
+  // never reaches the `capsule.request` emit (it throws at the fetch
+  // stage). Count it here so `tool.chain.capsuleCalls` stays honest and
+  // a chain whose duration ballooned is explained by a visible failure.
+  "capsule.timeout": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
+  "capsule.error": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
+  // A request that exhausted its 429 retry is a real (doubly-attempted)
+  // outbound call that throws before `capsule.request` fires — count it
+  // so a chain whose latency ballooned on rate-limit backoff is explained.
+  "capsule.ratelimit": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
   // Cache-hit events feed the aggregate so the chain stat is right
   // even on tools whose Capsule calls all hit the cache.
   "cache.hit": (ctx) => {
@@ -184,6 +200,15 @@ var CapsuleApiError = class extends Error {
   }
   status;
 };
+var CapsuleTimeoutError = class extends CapsuleApiError {
+  constructor() {
+    super(
+      504,
+      `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
+    );
+    this.name = "CapsuleTimeoutError";
+  }
+};
 function getToken() {
   const token = process.env["CAPSULE_API_TOKEN"];
   if (!token) {
@@ -264,30 +289,39 @@ async function mapAbort(p) {
     return await p;
   } catch (err) {
     if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
-      throw new CapsuleApiError(
-        504,
-        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
-      );
+      throw new CapsuleTimeoutError();
     }
     throw err;
   }
 }
 async function fetchWithTimeout(url, options) {
   const { options: opts, cleanup } = withTimeout(options);
+  const startedAt = Date.now();
   try {
     const res = await fetch(url, opts);
     return { res, cleanup };
   } catch (err) {
     cleanup();
-    if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
-      throw new CapsuleApiError(
-        504,
-        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
-      );
+    const isAbort = err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message));
+    emitCapsuleFailure(
+      options?.method ?? "GET",
+      url,
+      Date.now() - startedAt,
+      isAbort ? "timeout" : "network",
+      isAbort ? void 0 : err
+    );
+    if (isAbort) {
+      throw new CapsuleTimeoutError();
     }
     throw err;
   }
 }
+async function drainBody(res) {
+  try {
+    await res.body?.cancel();
+  } catch {
+  }
+}
 async function doFetch(url, options) {
   const startedAt = Date.now();
   const method = options?.method ?? "GET";
@@ -295,10 +329,13 @@ async function doFetch(url, options) {
   if (first.res.status === 429) {
     const delay = parseRateLimitDelay(first.res);
     first.cleanup();
+    await drainBody(first.res);
     await new Promise((resolve) => setTimeout(resolve, delay));
     const retried = await fetchWithTimeout(url, options);
     if (retried.res.status === 429) {
       retried.cleanup();
+      await drainBody(retried.res);
+      emitCapsuleRateLimited(method, url, Date.now() - startedAt);
       throw new CapsuleApiError(
         429,
         "Rate limit exceeded after one retry. Please slow down your requests."
@@ -310,8 +347,7 @@ async function doFetch(url, options) {
 }
 async function consumeBody(start, body) {
   try {
-    return await body();
-  } finally {
+    const result = await body();
     emitCapsuleRequest(
       start.method,
       start.url,
@@ -319,15 +355,31 @@ async function consumeBody(start, body) {
       Date.now() - start.startedAt,
       start.retriedAfter429
     );
+    return result;
+  } catch (err) {
+    if (err instanceof CapsuleTimeoutError) {
+      emitCapsuleFailure(start.method, start.url, Date.now() - start.startedAt, "timeout");
+    } else {
+      emitCapsuleRequest(
+        start.method,
+        start.url,
+        start.res,
+        Date.now() - start.startedAt,
+        start.retriedAfter429
+      );
+    }
+    throw err;
   }
 }
-function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
-  let path = "";
+function redactedPath(url) {
   try {
-    path = redactPath(new URL(url).pathname);
+    return redactPath(new URL(url).pathname);
   } catch {
-    path = "?";
+    return "?";
   }
+}
+function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
+  const path = redactedPath(url);
   const lenHeader = res.headers.get("content-length");
   const responseBytes = lenHeader ? Number.parseInt(lenHeader, 10) : 0;
   logEvent("capsule.request", {
@@ -339,6 +391,37 @@ function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
     ...retriedAfter429 ? { retriedAfter429: true } : {}
   });
 }
+function emitCapsuleFailure(method, url, elapsedMs, reason, err) {
+  const path = redactedPath(url);
+  if (reason === "timeout") {
+    logEvent(
+      "capsule.timeout",
+      { method, path, elapsedMs, timeoutMs: REQUEST_TIMEOUT_MS },
+      { force: true }
+    );
+    return;
+  }
+  const code = extractErrorCode(err);
+  logEvent(
+    "capsule.error",
+    { method, path, elapsedMs, ...code ? { code } : {} },
+    { force: true }
+  );
+}
+function emitCapsuleRateLimited(method, url, elapsedMs) {
+  logEvent(
+    "capsule.ratelimit",
+    { method, path: redactedPath(url), elapsedMs, status: 429 },
+    { force: true }
+  );
+}
+function extractErrorCode(err) {
+  const e = err;
+  const code = e?.cause?.code ?? e?.code;
+  if (typeof code === "string") return code;
+  if (typeof e?.name === "string" && e.name !== "Error") return e.name;
+  return void 0;
+}
 async function throwForStatus(res) {
   if (res.status === 401) {
     const detail = await parseErrorBody(res);
@@ -1142,6 +1225,22 @@ var abortControllers = /* @__PURE__ */ new Map();
 function registerAbortController(taskId, controller) {
   abortControllers.set(taskId, controller);
 }
+var evictionTimers = /* @__PURE__ */ new Map();
+var taskTtls = /* @__PURE__ */ new Map();
+function scheduleEviction(taskId, clientId, ttlMs) {
+  const existing = evictionTimers.get(taskId);
+  if (existing) clearTimeout(existing);
+  taskTtls.set(taskId, ttlMs);
+  const timer = setTimeout(() => {
+    owners.delete(taskId);
+    abortControllers.delete(taskId);
+    evictionTimers.delete(taskId);
+    taskTtls.delete(taskId);
+    logEvent("task.evicted", { taskId, clientId, reason: "ttl" });
+  }, ttlMs);
+  timer.unref?.();
+  evictionTimers.set(taskId, timer);
+}
 function countPerClient(clientId) {
   let n = 0;
   for (const owner of owners.values()) {
@@ -1195,12 +1294,7 @@ function createScopedTaskStore(clientId) {
         sessionId
       );
       owners.set(task.taskId, clientId);
-      const timer = setTimeout(() => {
-        owners.delete(task.taskId);
-        abortControllers.delete(task.taskId);
-        logEvent("task.evicted", { taskId: task.taskId, clientId, reason: "ttl" });
-      }, clampedTtl);
-      timer.unref?.();
+      scheduleEviction(task.taskId, clientId, clampedTtl);
       logEvent("task.created", {
         taskId: task.taskId,
         clientId,
@@ -1219,6 +1313,7 @@ function createScopedTaskStore(clientId) {
       }
       logEvent("task.transition", { taskId, clientId, status });
       await global.storeTaskResult(taskId, status, result, sessionId);
+      scheduleEviction(taskId, clientId, taskTtls.get(taskId) ?? getTasksConfig().defaultTtlMs);
     },
     async getTaskResult(taskId, sessionId) {
       if (owners.get(taskId) !== clientId) {
@@ -1238,6 +1333,7 @@ function createScopedTaskStore(clientId) {
       }
       if (status === "completed" || status === "failed" || status === "cancelled") {
         abortControllers.delete(taskId);
+        scheduleEviction(taskId, clientId, taskTtls.get(taskId) ?? getTasksConfig().defaultTtlMs);
       }
     },
     async listTasks(cursor, sessionId) {
@@ -1581,7 +1677,8 @@ async function chunkedMultiGet(base, responseKey, ids, params) {
       (chunkIds) => capsuleGet(`${base}/${chunkIds.join(",")}`, params)
     )
   );
-  return { [responseKey]: responses.flatMap((r) => r.data[responseKey] ?? []) };
+  const merged = responses.flatMap((r) => r.data[responseKey] ?? []);
+  return { ...responses[0]?.data ?? {}, [responseKey]: merged };
 }
 
 // src/tools/custom-field-helpers.ts
@@ -3223,7 +3320,7 @@ function createCapsuleMcpServer(opts) {
   const server = new McpServer(
     {
       name: "capsulemcp",
-      version: "1.7.0",
+      version: "1.8.0",
       description: "Read and (optionally) modify Capsule CRM data \u2014 parties, opportunities, projects, tasks, timeline entries, pipelines, tags.",
       websiteUrl: "https://github.com/soil-dev/capsulemcp",
       icons: ICONS

package/dist/index.js

@@ -31,6 +31,22 @@ var chainHandlers = {
   "capsule.request": (ctx) => {
     ctx.capsuleCalls += 1;
   },
+  // A timed-out or connection-failed call is still an attempt that
+  // never reaches the `capsule.request` emit (it throws at the fetch
+  // stage). Count it here so `tool.chain.capsuleCalls` stays honest and
+  // a chain whose duration ballooned is explained by a visible failure.
+  "capsule.timeout": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
+  "capsule.error": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
+  // A request that exhausted its 429 retry is a real (doubly-attempted)
+  // outbound call that throws before `capsule.request` fires — count it
+  // so a chain whose latency ballooned on rate-limit backoff is explained.
+  "capsule.ratelimit": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
   // Cache-hit events feed the aggregate so the chain stat is right
   // even on tools whose Capsule calls all hit the cache.
   "cache.hit": (ctx) => {
@@ -166,6 +182,15 @@ var CapsuleApiError = class extends Error {
   }
   status;
 };
+var CapsuleTimeoutError = class extends CapsuleApiError {
+  constructor() {
+    super(
+      504,
+      `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
+    );
+    this.name = "CapsuleTimeoutError";
+  }
+};
 function getToken() {
   const token = process.env["CAPSULE_API_TOKEN"];
   if (!token) {
@@ -246,30 +271,39 @@ async function mapAbort(p) {
     return await p;
   } catch (err) {
     if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
-      throw new CapsuleApiError(
-        504,
-        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
-      );
+      throw new CapsuleTimeoutError();
     }
     throw err;
   }
 }
 async function fetchWithTimeout(url, options) {
   const { options: opts, cleanup } = withTimeout(options);
+  const startedAt = Date.now();
   try {
     const res = await fetch(url, opts);
     return { res, cleanup };
   } catch (err) {
     cleanup();
-    if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
-      throw new CapsuleApiError(
-        504,
-        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
-      );
+    const isAbort = err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message));
+    emitCapsuleFailure(
+      options?.method ?? "GET",
+      url,
+      Date.now() - startedAt,
+      isAbort ? "timeout" : "network",
+      isAbort ? void 0 : err
+    );
+    if (isAbort) {
+      throw new CapsuleTimeoutError();
     }
     throw err;
   }
 }
+async function drainBody(res) {
+  try {
+    await res.body?.cancel();
+  } catch {
+  }
+}
 async function doFetch(url, options) {
   const startedAt = Date.now();
   const method = options?.method ?? "GET";
@@ -277,10 +311,13 @@ async function doFetch(url, options) {
   if (first.res.status === 429) {
     const delay = parseRateLimitDelay(first.res);
     first.cleanup();
+    await drainBody(first.res);
     await new Promise((resolve) => setTimeout(resolve, delay));
     const retried = await fetchWithTimeout(url, options);
     if (retried.res.status === 429) {
       retried.cleanup();
+      await drainBody(retried.res);
+      emitCapsuleRateLimited(method, url, Date.now() - startedAt);
       throw new CapsuleApiError(
         429,
         "Rate limit exceeded after one retry. Please slow down your requests."
@@ -292,8 +329,7 @@ async function doFetch(url, options) {
 }
 async function consumeBody(start, body) {
   try {
-    return await body();
-  } finally {
+    const result = await body();
     emitCapsuleRequest(
       start.method,
       start.url,
@@ -301,15 +337,31 @@ async function consumeBody(start, body) {
       Date.now() - start.startedAt,
       start.retriedAfter429
     );
+    return result;
+  } catch (err) {
+    if (err instanceof CapsuleTimeoutError) {
+      emitCapsuleFailure(start.method, start.url, Date.now() - start.startedAt, "timeout");
+    } else {
+      emitCapsuleRequest(
+        start.method,
+        start.url,
+        start.res,
+        Date.now() - start.startedAt,
+        start.retriedAfter429
+      );
+    }
+    throw err;
   }
 }
-function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
-  let path = "";
+function redactedPath(url) {
   try {
-    path = redactPath(new URL(url).pathname);
+    return redactPath(new URL(url).pathname);
   } catch {
-    path = "?";
+    return "?";
   }
+}
+function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
+  const path = redactedPath(url);
   const lenHeader = res.headers.get("content-length");
   const responseBytes = lenHeader ? Number.parseInt(lenHeader, 10) : 0;
   logEvent("capsule.request", {
@@ -321,6 +373,37 @@ function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
     ...retriedAfter429 ? { retriedAfter429: true } : {}
   });
 }
+function emitCapsuleFailure(method, url, elapsedMs, reason, err) {
+  const path = redactedPath(url);
+  if (reason === "timeout") {
+    logEvent(
+      "capsule.timeout",
+      { method, path, elapsedMs, timeoutMs: REQUEST_TIMEOUT_MS },
+      { force: true }
+    );
+    return;
+  }
+  const code = extractErrorCode(err);
+  logEvent(
+    "capsule.error",
+    { method, path, elapsedMs, ...code ? { code } : {} },
+    { force: true }
+  );
+}
+function emitCapsuleRateLimited(method, url, elapsedMs) {
+  logEvent(
+    "capsule.ratelimit",
+    { method, path: redactedPath(url), elapsedMs, status: 429 },
+    { force: true }
+  );
+}
+function extractErrorCode(err) {
+  const e = err;
+  const code = e?.cause?.code ?? e?.code;
+  if (typeof code === "string") return code;
+  if (typeof e?.name === "string" && e.name !== "Error") return e.name;
+  return void 0;
+}
 async function throwForStatus(res) {
   if (res.status === 401) {
     const detail = await parseErrorBody(res);
@@ -639,6 +722,22 @@ var abortControllers = /* @__PURE__ */ new Map();
 function registerAbortController(taskId, controller) {
   abortControllers.set(taskId, controller);
 }
+var evictionTimers = /* @__PURE__ */ new Map();
+var taskTtls = /* @__PURE__ */ new Map();
+function scheduleEviction(taskId, clientId, ttlMs) {
+  const existing = evictionTimers.get(taskId);
+  if (existing) clearTimeout(existing);
+  taskTtls.set(taskId, ttlMs);
+  const timer = setTimeout(() => {
+    owners.delete(taskId);
+    abortControllers.delete(taskId);
+    evictionTimers.delete(taskId);
+    taskTtls.delete(taskId);
+    logEvent("task.evicted", { taskId, clientId, reason: "ttl" });
+  }, ttlMs);
+  timer.unref?.();
+  evictionTimers.set(taskId, timer);
+}
 function countPerClient(clientId) {
   let n = 0;
   for (const owner of owners.values()) {
@@ -692,12 +791,7 @@ function createScopedTaskStore(clientId) {
         sessionId
       );
       owners.set(task.taskId, clientId);
-      const timer = setTimeout(() => {
-        owners.delete(task.taskId);
-        abortControllers.delete(task.taskId);
-        logEvent("task.evicted", { taskId: task.taskId, clientId, reason: "ttl" });
-      }, clampedTtl);
-      timer.unref?.();
+      scheduleEviction(task.taskId, clientId, clampedTtl);
       logEvent("task.created", {
         taskId: task.taskId,
         clientId,
@@ -716,6 +810,7 @@ function createScopedTaskStore(clientId) {
       }
       logEvent("task.transition", { taskId, clientId, status });
       await global.storeTaskResult(taskId, status, result, sessionId);
+      scheduleEviction(taskId, clientId, taskTtls.get(taskId) ?? getTasksConfig().defaultTtlMs);
     },
     async getTaskResult(taskId, sessionId) {
       if (owners.get(taskId) !== clientId) {
@@ -735,6 +830,7 @@ function createScopedTaskStore(clientId) {
       }
       if (status === "completed" || status === "failed" || status === "cancelled") {
         abortControllers.delete(taskId);
+        scheduleEviction(taskId, clientId, taskTtls.get(taskId) ?? getTasksConfig().defaultTtlMs);
       }
     },
     async listTasks(cursor, sessionId) {
@@ -1078,7 +1174,8 @@ async function chunkedMultiGet(base, responseKey, ids, params) {
       (chunkIds) => capsuleGet(`${base}/${chunkIds.join(",")}`, params)
     )
   );
-  return { [responseKey]: responses.flatMap((r) => r.data[responseKey] ?? []) };
+  const merged = responses.flatMap((r) => r.data[responseKey] ?? []);
+  return { ...responses[0]?.data ?? {}, [responseKey]: merged };
 }
 
 // src/tools/custom-field-helpers.ts
@@ -2720,7 +2817,7 @@ function createCapsuleMcpServer(opts) {
   const server2 = new McpServer(
     {
       name: "capsulemcp",
-      version: "1.7.0",
+      version: "1.8.0",
       description: "Read and (optionally) modify Capsule CRM data \u2014 parties, opportunities, projects, tasks, timeline entries, pipelines, tags.",
       websiteUrl: "https://github.com/soil-dev/capsulemcp",
       icons: ICONS
@@ -3457,7 +3554,8 @@ if (!process.env["CAPSULE_API_TOKEN"]) {
   );
   process.exit(1);
 }
-var server = createCapsuleMcpServer();
+var STDIO_CLIENT_ID = "stdio-local";
+var server = createCapsuleMcpServer({ clientId: STDIO_CLIENT_ID });
 var transport = new StdioServerTransport();
 if (isReadOnly()) {
   console.error("[capsulemcp] read-only mode: write/delete tools are not registered");

package/package.json

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