@gethmy/mcp 2.12.0 → 2.13.0

package/src/server.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { syncFull, syncPull, syncPush } from "@harmony/memory";
@@ -67,6 +68,99 @@ import { lintTags, normalizeTags } from "./memory-tags.js";
 import { onboardNewUser } from "./onboard.js";
 import { stripSkillPreamble } from "./skills.js";
 
+// --- Signed-upload handshake (artifacts & card attachments) ---
+// Mirror the edge-fn caps so a too-large `filePath`/`base64Data` fails fast in
+// the client instead of being read fully into memory and round-tripped only to
+// be rejected server-side (closes the #345 "no size pre-check" finding). The
+// finalize endpoint re-enforces these as the real security boundary.
+const MAX_ARTIFACT_SIZE = 2 * 1024 * 1024; // 2 MB — keep in sync with harmony-api
+const MAX_ATTACHMENT_SIZE = 5 * 1024 * 1024; // 5 MB — keep in sync with harmony-api
+
+/** Decoded byte length of a base64 string, tolerating a leading `data:` URL
+ * prefix (the edge fn strips it; we strip a copy only to measure). */
+function base64ByteLength(base64: string): number {
+  const stripped = base64.replace(/^data:[^,]*,/, "");
+  return Buffer.from(stripped, "base64").byteLength;
+}
+
+function sha256Hex(bytes: Buffer): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Read a local file for a direct-to-storage upload, rejecting empty and
+ * over-cap before any network round-trip. `kind` shapes the error copy. */
+async function readFileForUpload(
+  filePath: string,
+  maxSize: number,
+  kind: "attachment" | "artifact",
+): Promise<Buffer> {
+  const bytes = await readFile(filePath);
+  if (bytes.byteLength === 0) {
+    throw new Error(`File is empty: ${filePath}`);
+  }
+  if (bytes.byteLength > maxSize) {
+    const mb = Math.round(maxSize / (1024 * 1024));
+    throw new Error(
+      `File is ${bytes.byteLength} bytes, over the ${maxSize}-byte (${mb}MB) ${kind} limit.`,
+    );
+  }
+  return bytes;
+}
+
+/** Enforce the exactly-one-of-scope rule shared by the artifact upload,
+ * upload-url, and finalize tools. */
+function requireExactlyOneScope(scope: {
+  cardId?: string;
+  planId?: string;
+  workspaceId?: string;
+}): void {
+  if (
+    [scope.cardId, scope.planId, scope.workspaceId].filter(Boolean).length !== 1
+  ) {
+    throw new Error("Provide exactly one of cardId, planId, or workspaceId.");
+  }
+}
+
+/** PUT raw bytes straight to a Supabase signed upload URL (the token rides in
+ * the URL query). Used by the stdio internal handshake; the hosted server can't
+ * read local disk, so there the agent drives this PUT itself via the two-step
+ * tools. */
+const SIGNED_UPLOAD_TIMEOUT_MS = 30_000;
+
+async function putToSignedUrl(
+  uploadUrl: string,
+  bytes: Uint8Array,
+  contentType: string,
+): Promise<void> {
+  let res: Response;
+  try {
+    res = await fetch(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": contentType },
+      // Cast around the TS 5.7 lib regression where the now-generic
+      // `Uint8Array<ArrayBufferLike>` no longer matches `BodyInit`'s
+      // `ArrayBuffer`-pinned `BufferSource`. The bytes are a valid fetch body.
+      body: bytes as unknown as BodyInit,
+      // Bound the upload so a stalled storage PUT can't hang the call
+      // indefinitely (there is no watchdog at this layer).
+      signal: AbortSignal.timeout(SIGNED_UPLOAD_TIMEOUT_MS),
+    });
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "TimeoutError") {
+      throw new Error(
+        `Direct storage upload timed out after ${SIGNED_UPLOAD_TIMEOUT_MS}ms.`,
+      );
+    }
+    throw err;
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(
+      `Direct storage upload failed: ${res.status}${detail ? ` — ${detail}` : ""}`,
+    );
+  }
+}
+
 /**
  * Dependencies injected into tool handlers.
  * Allows the same handlers to be used by both stdio and remote (HTTP) transports.
@@ -665,7 +759,7 @@ export const TOOLS = {
   },
   harmony_upload_card_attachment: {
     description:
-      "Upload a file attachment to a card (e.g. a pasted screenshot or a document). Provide the file either as `filePath` (a local path the MCP server can read — works in local/stdio mode) or as `base64Data` (raw base64 bytes — works everywhere, including remote mode). Max 5MB. Allowed: PNG, JPEG, GIF, WebP, HEIC/HEIF, PDF, DOC/DOCX, XLS/XLSX, TXT, CSV. Returns the stored attachment with a short-lived signed URL.",
+      "Upload a file attachment to a card (e.g. a pasted screenshot or a document). Provide the file either as `filePath` (a local path the MCP server can read — works in local/stdio mode) or as `base64Data` (raw base64 bytes — works everywhere, including remote mode). With `filePath` the server uploads direct-to-storage (no base64 through the model context); `base64Data` is the small-file fallback. Max 5MB. Allowed: PNG, JPEG, GIF, WebP, HEIC/HEIF, PDF, DOC/DOCX, XLS/XLSX, TXT, CSV. Returns the stored attachment with a short-lived signed URL. For large files on the hosted MCP server (where only base64Data works), prefer the two-step harmony_request_card_attachment_upload_url + harmony_finalize_card_attachment handshake, which keeps bytes out of the model context.",
     inputSchema: {
       type: "object",
       properties: {
@@ -694,6 +788,65 @@ export const TOOLS = {
       required: ["cardId"],
     },
   },
+  harmony_request_card_attachment_upload_url: {
+    description:
+      "Step 1 of the agent-driven card-attachment upload — use this for large files or when running against the hosted MCP server (which cannot read your local disk). Mints a one-shot signed Supabase Storage upload URL for a server-chosen path under the card. Provide cardId, fileName (with extension), the byte size, and optionally fileType. Returns { uploadUrl, token, storagePath, fileType }. Next: PUT the raw bytes straight to uploadUrl (e.g. `curl -X PUT --data-binary @file.png '<uploadUrl>'`) — no bytes pass through the model context — then call harmony_finalize_card_attachment with the returned storagePath. Max 5MB; allowed: PNG, JPEG, GIF, WebP, HEIC/HEIF, PDF, DOC/DOCX, XLS/XLSX, TXT, CSV.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID" },
+        fileName: {
+          type: "string",
+          description: "File name including extension (e.g. 'screenshot.png').",
+        },
+        fileType: {
+          type: "string",
+          description:
+            "Optional MIME type (e.g. 'image/png'). Inferred from the file extension when omitted.",
+        },
+        size: {
+          type: "number",
+          description: "File size in bytes (rejected early if over 5MB).",
+        },
+      },
+      required: ["cardId", "fileName", "size"],
+    },
+  },
+  harmony_finalize_card_attachment: {
+    description:
+      "Step 2 of the agent-driven card-attachment upload. After PUTting the bytes to the signed uploadUrl from harmony_request_card_attachment_upload_url, call this with the returned storagePath to validate and register the attachment. The server re-downloads the object and enforces size, an allowlisted content-type (magic-byte sniff, never the declared type), and — when you pass sha256 — an integrity check, deleting the object and failing on any mismatch. Returns the stored attachment with a short-lived signed URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID" },
+        storagePath: {
+          type: "string",
+          description:
+            "The storagePath returned by harmony_request_card_attachment_upload_url.",
+        },
+        fileName: {
+          type: "string",
+          description: "File name including extension (e.g. 'screenshot.png').",
+        },
+        fileType: {
+          type: "string",
+          description:
+            "Optional MIME type; inferred from the extension when omitted.",
+        },
+        sha256: {
+          type: "string",
+          description:
+            "Optional hex SHA-256 of the uploaded bytes; verified against the stored object.",
+        },
+        size: {
+          type: "number",
+          description:
+            "Optional byte size (advisory; re-validated server-side).",
+        },
+      },
+      required: ["cardId", "storagePath", "fileName"],
+    },
+  },
   harmony_classify_card: {
     description:
       "Classify a card with the LLM classifier: sets `intent` (plan/think/implement/review), `complexity_score` (0-10), and `model_tier` (simple/advanced/research), stamps `classified_at`, and applies the canonical type label (feature/bug/idea). Use this right after creating a card (e.g. in the `hmy-new` flow) so it's classified in-flow instead of waiting for it to surface on the web board. Idempotent — safe to re-run. Never touches the user-owned `model_override`.",
@@ -707,7 +860,7 @@ export const TOOLS = {
   },
   harmony_upload_artifact: {
     description:
-      "Host a self-contained HTML document (e.g. a visual design draft or diagram) in Harmony and link it to a card, a plan, or a workspace. The file is stored privately and rendered in-app inside a sandboxed cross-origin iframe. Provide exactly one of cardId, planId, or workspaceId. Supply the HTML as `filePath` (a local path the MCP server can read) or `base64Data`. Only text/html, max 2MB. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link.",
+      "Host a self-contained HTML document (e.g. a visual design draft or diagram) in Harmony and link it to a card, a plan, or a workspace. The file is stored privately and rendered in-app inside a sandboxed cross-origin iframe. Provide exactly one of cardId, planId, or workspaceId. Supply the HTML as `filePath` (a local path the MCP server can read — uploaded direct-to-storage, no base64 through the model context) or `base64Data` (the small-file fallback). Only text/html, max 2MB. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link. For large files on the hosted MCP server (where only base64Data works), prefer the two-step harmony_request_artifact_upload_url + harmony_finalize_artifact handshake, which keeps bytes out of the model context.",
     inputSchema: {
       type: "object",
       properties: {
@@ -736,6 +889,69 @@ export const TOOLS = {
       required: [],
     },
   },
+  harmony_request_artifact_upload_url: {
+    description:
+      "Step 1 of the agent-driven artifact upload — use this for large files or when running against the hosted MCP server (which cannot read your local disk), instead of streaming base64 through the model context. Mints a one-shot signed Supabase Storage upload URL for a server-chosen path. Provide exactly one of cardId/planId/workspaceId, optionally a title and the byte size. Returns { uploadUrl, token, storagePath }. Next: PUT the raw HTML bytes straight to uploadUrl (e.g. `curl -X PUT --data-binary @doc.html '<uploadUrl>'`), then call harmony_finalize_artifact with the returned storagePath. Only text/html, max 2MB.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description:
+            "Display title (defaults to the file basename at finalize).",
+        },
+        cardId: { type: "string", description: "Link to this card (UUID)." },
+        planId: { type: "string", description: "Link to this plan (UUID)." },
+        workspaceId: {
+          type: "string",
+          description:
+            "Attach to this workspace as a standalone artifact (UUID).",
+        },
+        contentType: {
+          type: "string",
+          description: "MIME type; only 'text/html' is accepted (the default).",
+        },
+        size: {
+          type: "number",
+          description: "File size in bytes (rejected early if over 2MB).",
+        },
+      },
+      required: [],
+    },
+  },
+  harmony_finalize_artifact: {
+    description:
+      "Step 2 of the agent-driven artifact upload. After PUTting the HTML bytes to the signed uploadUrl from harmony_request_artifact_upload_url, call this with the returned storagePath to validate and register the artifact. The server re-downloads the object and enforces size, the text/html content-type (magic-byte sniff), and — when you pass sha256 — an integrity check, deleting the object and failing on any mismatch. Provide the same one of cardId/planId/workspaceId used for the upload URL. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        storagePath: {
+          type: "string",
+          description:
+            "The storagePath returned by harmony_request_artifact_upload_url.",
+        },
+        title: { type: "string", description: "Display title." },
+        cardId: { type: "string", description: "Link to this card (UUID)." },
+        planId: { type: "string", description: "Link to this plan (UUID)." },
+        workspaceId: {
+          type: "string",
+          description:
+            "Attach to this workspace as a standalone artifact (UUID).",
+        },
+        sha256: {
+          type: "string",
+          description:
+            "Optional hex SHA-256 of the uploaded bytes; verified against the stored object.",
+        },
+        size: {
+          type: "number",
+          description:
+            "Optional byte size (advisory; re-validated server-side).",
+        },
+      },
+      required: ["storagePath"],
+    },
+  },
   harmony_share_artifact: {
     description:
       "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL.",
@@ -2690,7 +2906,7 @@ async function handleToolCall(
         args.filePath != null ? z.string().parse(args.filePath) : undefined;
       const base64Data =
         args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
-      let fileName =
+      const fileName =
         args.fileName != null ? z.string().parse(args.fileName) : undefined;
       const contentType =
         args.contentType != null
@@ -2701,29 +2917,51 @@ async function handleToolCall(
         throw new Error("Provide either filePath or base64Data, not both.");
       }
 
-      let data: string;
       if (filePath) {
-        const bytes = await readFile(filePath);
-        if (bytes.byteLength === 0) {
-          throw new Error(`File is empty: ${filePath}`);
-        }
-        data = bytes.toString("base64");
-        fileName = fileName || basename(filePath);
-      } else if (base64Data) {
+        // Server can read the file → upload direct-to-storage via the handshake
+        // (no base64 through the model context or the edge-fn JSON body).
+        const bytes = await readFileForUpload(
+          filePath,
+          MAX_ATTACHMENT_SIZE,
+          "attachment",
+        );
+        const resolvedName = fileName || basename(filePath);
+        const signed = await client.requestCardAttachmentUploadUrl(cardId, {
+          fileName: resolvedName,
+          fileType: contentType,
+          size: bytes.byteLength,
+        });
+        await putToSignedUrl(
+          signed.uploadUrl,
+          bytes,
+          contentType || signed.fileType || "application/octet-stream",
+        );
+        return await client.finalizeCardAttachment(cardId, {
+          storagePath: signed.storagePath,
+          fileName: resolvedName,
+          fileType: contentType || signed.fileType,
+          sha256: sha256Hex(bytes),
+          size: bytes.byteLength,
+        });
+      }
+
+      if (base64Data) {
         if (!fileName) {
           throw new Error("fileName is required when using base64Data.");
         }
-        data = base64Data;
-      } else {
-        throw new Error("Provide either filePath or base64Data.");
+        if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
+          throw new Error(
+            `File is over the 5MB attachment limit. Use the harmony_request_card_attachment_upload_url + harmony_finalize_card_attachment handshake for large files.`,
+          );
+        }
+        return await client.uploadCardAttachment(cardId, {
+          fileName,
+          data: base64Data,
+          fileType: contentType,
+        });
       }
 
-      const result = await client.uploadCardAttachment(cardId, {
-        fileName: fileName as string,
-        data,
-        fileType: contentType,
-      });
-      return result;
+      throw new Error("Provide either filePath or base64Data.");
     }
 
     case "harmony_upload_artifact": {
@@ -2737,12 +2975,7 @@ async function handleToolCall(
         args.workspaceId != null
           ? z.string().uuid().parse(args.workspaceId)
           : undefined;
-      const anchors = [cardId, planId, workspaceId].filter(Boolean);
-      if (anchors.length !== 1) {
-        throw new Error(
-          "Provide exactly one of cardId, planId, or workspaceId.",
-        );
-      }
+      requireExactlyOneScope({ cardId, planId, workspaceId });
 
       const filePath =
         args.filePath != null ? z.string().parse(args.filePath) : undefined;
@@ -2752,29 +2985,149 @@ async function handleToolCall(
         throw new Error("Provide either filePath or base64Data, not both.");
       }
 
-      let data: string;
-      let inferredTitle = title;
       if (filePath) {
-        const bytes = await readFile(filePath);
-        if (bytes.byteLength === 0) {
-          throw new Error(`File is empty: ${filePath}`);
+        // Server can read the file → upload direct-to-storage via the handshake
+        // (no base64 through the model context or the edge-fn JSON body).
+        const bytes = await readFileForUpload(
+          filePath,
+          MAX_ARTIFACT_SIZE,
+          "artifact",
+        );
+        const resolvedTitle = title || basename(filePath);
+        const signed = await client.requestArtifactUploadUrl({
+          title: resolvedTitle,
+          cardId,
+          planId,
+          workspaceId,
+          contentType: "text/html",
+          size: bytes.byteLength,
+        });
+        await putToSignedUrl(signed.uploadUrl, bytes, "text/html");
+        return await client.finalizeArtifact({
+          storagePath: signed.storagePath,
+          sha256: sha256Hex(bytes),
+          size: bytes.byteLength,
+          title: resolvedTitle,
+          cardId,
+          planId,
+          workspaceId,
+        });
+      }
+
+      if (base64Data) {
+        if (base64ByteLength(base64Data) > MAX_ARTIFACT_SIZE) {
+          throw new Error(
+            `Artifact is over the 2MB limit. Use the harmony_request_artifact_upload_url + harmony_finalize_artifact handshake for large files.`,
+          );
         }
-        data = bytes.toString("base64");
-        inferredTitle = inferredTitle || basename(filePath);
-      } else if (base64Data) {
-        data = base64Data;
-      } else {
-        throw new Error("Provide either filePath or base64Data.");
+        return await client.uploadArtifact({
+          title,
+          cardId,
+          planId,
+          workspaceId,
+          data: base64Data,
+        });
       }
 
-      const result = await client.uploadArtifact({
-        title: inferredTitle,
+      throw new Error("Provide either filePath or base64Data.");
+    }
+
+    case "harmony_request_artifact_upload_url": {
+      const title =
+        args.title != null ? z.string().parse(args.title) : undefined;
+      const cardId =
+        args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
+      const planId =
+        args.planId != null ? z.string().uuid().parse(args.planId) : undefined;
+      const workspaceId =
+        args.workspaceId != null
+          ? z.string().uuid().parse(args.workspaceId)
+          : undefined;
+      requireExactlyOneScope({ cardId, planId, workspaceId });
+      const contentType =
+        args.contentType != null
+          ? z.string().parse(args.contentType)
+          : undefined;
+      const size =
+        args.size != null ? z.number().positive().parse(args.size) : undefined;
+      if (size != null && size > MAX_ARTIFACT_SIZE) {
+        throw new Error(
+          `Declared size ${size} bytes is over the ${MAX_ARTIFACT_SIZE}-byte (2MB) artifact limit.`,
+        );
+      }
+      return await client.requestArtifactUploadUrl({
+        title,
         cardId,
         planId,
         workspaceId,
-        data,
+        contentType,
+        size,
+      });
+    }
+
+    case "harmony_finalize_artifact": {
+      const storagePath = z.string().parse(args.storagePath);
+      const title =
+        args.title != null ? z.string().parse(args.title) : undefined;
+      const cardId =
+        args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
+      const planId =
+        args.planId != null ? z.string().uuid().parse(args.planId) : undefined;
+      const workspaceId =
+        args.workspaceId != null
+          ? z.string().uuid().parse(args.workspaceId)
+          : undefined;
+      requireExactlyOneScope({ cardId, planId, workspaceId });
+      const sha256 =
+        args.sha256 != null ? z.string().parse(args.sha256) : undefined;
+      const size =
+        args.size != null ? z.number().positive().parse(args.size) : undefined;
+      return await client.finalizeArtifact({
+        storagePath,
+        sha256,
+        size,
+        title,
+        cardId,
+        planId,
+        workspaceId,
+      });
+    }
+
+    case "harmony_request_card_attachment_upload_url": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const fileName = z.string().parse(args.fileName);
+      const fileType =
+        args.fileType != null ? z.string().parse(args.fileType) : undefined;
+      const size = z.number().positive().parse(args.size);
+      if (size > MAX_ATTACHMENT_SIZE) {
+        throw new Error(
+          `Declared size ${size} bytes is over the ${MAX_ATTACHMENT_SIZE}-byte (5MB) attachment limit.`,
+        );
+      }
+      return await client.requestCardAttachmentUploadUrl(cardId, {
+        fileName,
+        fileType,
+        size,
+      });
+    }
+
+    case "harmony_finalize_card_attachment": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const storagePath = z.string().parse(args.storagePath);
+      const fileName = z.string().parse(args.fileName);
+      const fileType =
+        args.fileType != null ? z.string().parse(args.fileType) : undefined;
+      const sha256 =
+        args.sha256 != null ? z.string().parse(args.sha256) : undefined;
+      const size =
+        args.size != null ? z.number().positive().parse(args.size) : undefined;
+      return await client.finalizeCardAttachment(cardId, {
+        storagePath,
+        fileName,
+        fileType,
+        sha256,
+        size,
       });
-      return result;
     }
 
     case "harmony_share_artifact": {