@capacms/mcp 0.2.0 → 0.3.0

package/lib/uploader-retry.mjs

@@ -0,0 +1,82 @@
+/**
+ * uploader-retry.mjs — send to Capa's uploader, and wait out a busy one.
+ *
+ * The uploader runs a few uploads at once per machine and lets one project,
+ * or one person, hold half of them (apps/uploader/app.js). Past that it
+ * answers 503 with `Retry-After` and a `reason`: uploader_busy, project_busy
+ * or account_busy. Busy is not a failure: the same request a few seconds
+ * later goes through. `sendToUploader` waits `Retry-After` (at most 10 s, up
+ * to a quarter more for jitter, never past 10 s) and sends again, up to 4
+ * times. Every other answer comes back as it is, 408 too_slow and 413
+ * too_large included: the same file sent the same way gets the same answer.
+ *
+ * capa_upload_media (media-tools.mjs) sends through this, and so does
+ * `capa media upload`, which runs that tool. The admin follows the same rule
+ * (apps/admin/src/lib/external-apis/upload-queue.ts); keep the reasons and
+ * the numbers the same in both.
+ *
+ * `send` makes ONE attempt and answers a fetch Response. It is called again
+ * for each retry, so it builds its body and its timeout signal each time: a
+ * FormData over a file Blob (`fs.openAsBlob`) reads the file again.
+ */
+
+/** The `reason`s of the uploader's busy 503s. Any other 503 is answered as it is. */
+export const BUSY_REASONS = new Set(["uploader_busy", "project_busy", "account_busy"]);
+
+/** How many times one upload is sent again after a busy answer. */
+export const BUSY_RETRIES = 4;
+
+/** The longest one wait lasts, whatever `Retry-After` says. */
+export const MAX_BUSY_WAIT_MS = 10_000;
+
+/** The wait when a busy answer names none. The uploader sends 5. */
+const DEFAULT_BUSY_WAIT_SECONDS = 5;
+
+function seconds(value) {
+  if (value === undefined || value === null || value === "") return null;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+/**
+ * How long to wait before sending again, or null when the answer is not a
+ * busy one. `retryAfter` is the header's value; the body's `retryAfter`
+ * stands in when there is none.
+ */
+export function busyWaitMs(status, body, retryAfter, random = Math.random) {
+  if (status !== 503 || !body || typeof body !== "object" || !BUSY_REASONS.has(body.reason)) return null;
+  const wait = seconds(retryAfter) ?? seconds(body.retryAfter) ?? DEFAULT_BUSY_WAIT_SECONDS;
+  return Math.round(Math.min(MAX_BUSY_WAIT_MS, wait * 1000 * (1 + 0.25 * random())));
+}
+
+const pause = (ms, signal) =>
+  new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      resolve();
+    }, { once: true });
+  });
+
+/**
+ * Send with `send`, waiting out busy answers. Answers the last attempt as
+ * `{ res, text, body, retries }`: its Response, its body as text and parsed
+ * (null when not JSON), and how many times it was sent again.
+ */
+export async function sendToUploader(send, { retries = BUSY_RETRIES, random = Math.random, sleep = pause, signal } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    const res = await send();
+    const text = await res.text();
+    let body = null;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = null;
+    }
+    const wait = attempt < retries ? busyWaitMs(res.status, body, res.headers.get("retry-after"), random) : null;
+    if (wait === null || signal?.aborted) return { res, text, body, retries: attempt };
+    await sleep(wait, signal);
+    if (signal?.aborted) return { res, text, body, retries: attempt };
+  }
+}

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@capacms/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "stdio MCP server for Capa, shaped for agents rather than one tool per endpoint.",
   "license": "UNLICENSED",
-  "homepage": "https://docs.capacms.com/api/ai-assistants",
+  "homepage": "https://docs.capacms.com/ai/mcp",
   "type": "module",
   "bin": {
     "capa-mcp": "bin/capa-mcp.mjs"
   },
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./package.json": "./package.json"
+  },
   "files": [
     "bin",
     "lib"
@@ -19,6 +23,6 @@
     "node": ">=20.3"
   },
   "scripts": {
-    "test": "node --test test/comments.test.mjs test/session.test.mjs test/server.test.mjs test/bound.test.mjs test/document.test.mjs test/graphql-tools.test.mjs test/graphql-contract.test.mjs test/package.test.mjs"
+    "test": "node --test test/comments.test.mjs test/session.test.mjs test/server.test.mjs test/bound.test.mjs test/document.test.mjs test/graphql-tools.test.mjs test/graphql-contract.test.mjs test/package.test.mjs test/index.test.mjs test/entry-tools.test.mjs test/tool-contract.test.mjs test/media-tools.test.mjs test/uploader-retry.test.mjs test/hosted.test.mjs"
   }
 }