@gethmy/mcp 2.19.0 → 2.20.0

package/dist/cli.js

@@ -3644,6 +3644,43 @@ async function putToSignedUrl(uploadUrl, bytes, contentType) {
     throw new Error(`Direct storage upload failed: ${res.status}${detail ? ` — ${detail}` : ""}`);
   }
 }
+async function attachFileToCard(client3, cardId, file) {
+  const { filePath, base64Data, fileName, contentType } = file;
+  if (filePath && base64Data) {
+    throw new Error("Provide either filePath or base64Data, not both.");
+  }
+  if (filePath) {
+    const bytes = await readFileForUpload(filePath, MAX_ATTACHMENT_SIZE, "attachment");
+    const resolvedName = fileName || basename(filePath);
+    const signed = await client3.requestCardAttachmentUploadUrl(cardId, {
+      fileName: resolvedName,
+      fileType: contentType,
+      size: bytes.byteLength
+    });
+    await putToSignedUrl(signed.uploadUrl, bytes, contentType || signed.fileType || "application/octet-stream");
+    return await client3.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.");
+    }
+    if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
+      throw new Error(`File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`);
+    }
+    return await client3.uploadCardAttachment(cardId, {
+      fileName,
+      data: base64Data,
+      fileType: contentType
+    });
+  }
+  throw new Error("Provide either filePath or base64Data.");
+}
 var memorySessions = new Map;
 function parseLabelList(raw) {
   if (raw === undefined || raw === null)
@@ -3800,7 +3837,7 @@ function cleanupMemorySession(cardId) {
 }
 var TOOLS = {
   harmony_create_card: {
-    description: "Create a new card in a Kanban column",
+    description: "Create a new card in a Kanban column. Optionally attach reference files " + "(e.g. a screenshot from the prompt) at creation time via `attachments` — " + "the card is created first, then each file is uploaded to it.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3823,6 +3860,31 @@ var TOOLS = {
         planId: {
           type: "string",
           description: "Plan ID to link this card to (optional). Links the card to that plan via its plan_id."
+        },
+        attachments: {
+          type: "array",
+          description: "Optional reference files to attach to the new card (e.g. a screenshot from the prompt). " + "Max 5MB each; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV. Each file's bytes " + "come from `filePath` (absolute local path the server reads, preferred) or `base64Data` " + "(small-file fallback; requires fileName). NOTE: a pasted image only attaches if your " + "harness has written it to a local file you can pass as filePath — a model cannot re-emit " + "pasted image bytes into base64Data. Per-file failures never block card creation; they are " + "reported back in the result's `attachments` array so you can retry via harmony_upload.",
+          items: {
+            type: "object",
+            properties: {
+              filePath: {
+                type: "string",
+                description: "Absolute path to a local file the server can read. Mutually exclusive with base64Data."
+              },
+              base64Data: {
+                type: "string",
+                description: "Base64-encoded bytes (a `data:` URL prefix is accepted and stripped). Requires fileName. Mutually exclusive with filePath."
+              },
+              fileName: {
+                type: "string",
+                description: "File name including extension (required with base64Data; else defaults to the filePath basename)."
+              },
+              contentType: {
+                type: "string",
+                description: "Optional MIME type (inferred from the extension when omitted)."
+              }
+            }
+          }
         }
       },
       required: ["title"]
@@ -5637,6 +5699,12 @@ async function handleToolCall(name, args, deps) {
     case "harmony_create_card": {
       const title = z.string().min(1).max(500).parse(args.title);
       const projectId = args.projectId || getProjectId();
+      const attachments = args.attachments != null ? z.array(z.object({
+        filePath: z.string().optional(),
+        base64Data: z.string().optional(),
+        fileName: z.string().optional(),
+        contentType: z.string().optional()
+      })).parse(args.attachments) : [];
       const result = await client3.createCard(projectId, {
         title,
         columnId: args.columnId,
@@ -5645,7 +5713,30 @@ async function handleToolCall(name, args, deps) {
         assigneeId: args.assigneeId,
         planId: args.planId
       });
-      return { success: true, ...result };
+      if (attachments.length === 0) {
+        return { success: true, ...result };
+      }
+      const cardId = result.card?.id;
+      if (!cardId) {
+        return {
+          success: true,
+          ...result,
+          attachmentWarning: "Card created, but attachments were skipped: no card id was returned to upload against."
+        };
+      }
+      const attachmentResults = await Promise.all(attachments.map(async (file) => {
+        try {
+          const uploaded = await attachFileToCard(client3, cardId, file);
+          return { ok: true, attachment: uploaded.attachment };
+        } catch (err) {
+          return {
+            ok: false,
+            fileName: file.fileName ?? file.filePath ?? "(unnamed)",
+            error: err instanceof Error ? err.message : String(err)
+          };
+        }
+      }));
+      return { success: true, ...result, attachments: attachmentResults };
     }
     case "harmony_update_card": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -5931,37 +6022,12 @@ ${list}
         const cardId2 = z.string().uuid().parse(args.cardId);
         const fileName = args.fileName != null ? z.string().parse(args.fileName) : undefined;
         const contentType = args.contentType != null ? z.string().parse(args.contentType) : undefined;
-        if (filePath) {
-          const bytes = await readFileForUpload(filePath, MAX_ATTACHMENT_SIZE, "attachment");
-          const resolvedName = fileName || basename(filePath);
-          const signed = await client3.requestCardAttachmentUploadUrl(cardId2, {
-            fileName: resolvedName,
-            fileType: contentType,
-            size: bytes.byteLength
-          });
-          await putToSignedUrl(signed.uploadUrl, bytes, contentType || signed.fileType || "application/octet-stream");
-          return await client3.finalizeCardAttachment(cardId2, {
-            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.");
-          }
-          if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
-            throw new Error(`File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`);
-          }
-          return await client3.uploadCardAttachment(cardId2, {
-            fileName,
-            data: base64Data,
-            fileType: contentType
-          });
-        }
-        throw new Error("Provide either filePath or base64Data.");
+        return await attachFileToCard(client3, cardId2, {
+          filePath,
+          base64Data,
+          fileName,
+          contentType
+        });
       }
       const title = args.title != null ? z.string().parse(args.title) : undefined;
       const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;

package/dist/index.js

@@ -3639,6 +3639,43 @@ async function putToSignedUrl(uploadUrl, bytes, contentType) {
     throw new Error(`Direct storage upload failed: ${res.status}${detail ? ` — ${detail}` : ""}`);
   }
 }
+async function attachFileToCard(client3, cardId, file) {
+  const { filePath, base64Data, fileName, contentType } = file;
+  if (filePath && base64Data) {
+    throw new Error("Provide either filePath or base64Data, not both.");
+  }
+  if (filePath) {
+    const bytes = await readFileForUpload(filePath, MAX_ATTACHMENT_SIZE, "attachment");
+    const resolvedName = fileName || basename(filePath);
+    const signed = await client3.requestCardAttachmentUploadUrl(cardId, {
+      fileName: resolvedName,
+      fileType: contentType,
+      size: bytes.byteLength
+    });
+    await putToSignedUrl(signed.uploadUrl, bytes, contentType || signed.fileType || "application/octet-stream");
+    return await client3.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.");
+    }
+    if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
+      throw new Error(`File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`);
+    }
+    return await client3.uploadCardAttachment(cardId, {
+      fileName,
+      data: base64Data,
+      fileType: contentType
+    });
+  }
+  throw new Error("Provide either filePath or base64Data.");
+}
 var memorySessions = new Map;
 function parseLabelList(raw) {
   if (raw === undefined || raw === null)
@@ -3795,7 +3832,7 @@ function cleanupMemorySession(cardId) {
 }
 var TOOLS = {
   harmony_create_card: {
-    description: "Create a new card in a Kanban column",
+    description: "Create a new card in a Kanban column. Optionally attach reference files " + "(e.g. a screenshot from the prompt) at creation time via `attachments` — " + "the card is created first, then each file is uploaded to it.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3818,6 +3855,31 @@ var TOOLS = {
         planId: {
           type: "string",
           description: "Plan ID to link this card to (optional). Links the card to that plan via its plan_id."
+        },
+        attachments: {
+          type: "array",
+          description: "Optional reference files to attach to the new card (e.g. a screenshot from the prompt). " + "Max 5MB each; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV. Each file's bytes " + "come from `filePath` (absolute local path the server reads, preferred) or `base64Data` " + "(small-file fallback; requires fileName). NOTE: a pasted image only attaches if your " + "harness has written it to a local file you can pass as filePath — a model cannot re-emit " + "pasted image bytes into base64Data. Per-file failures never block card creation; they are " + "reported back in the result's `attachments` array so you can retry via harmony_upload.",
+          items: {
+            type: "object",
+            properties: {
+              filePath: {
+                type: "string",
+                description: "Absolute path to a local file the server can read. Mutually exclusive with base64Data."
+              },
+              base64Data: {
+                type: "string",
+                description: "Base64-encoded bytes (a `data:` URL prefix is accepted and stripped). Requires fileName. Mutually exclusive with filePath."
+              },
+              fileName: {
+                type: "string",
+                description: "File name including extension (required with base64Data; else defaults to the filePath basename)."
+              },
+              contentType: {
+                type: "string",
+                description: "Optional MIME type (inferred from the extension when omitted)."
+              }
+            }
+          }
         }
       },
       required: ["title"]
@@ -5632,6 +5694,12 @@ async function handleToolCall(name, args, deps) {
     case "harmony_create_card": {
       const title = z.string().min(1).max(500).parse(args.title);
       const projectId = args.projectId || getProjectId();
+      const attachments = args.attachments != null ? z.array(z.object({
+        filePath: z.string().optional(),
+        base64Data: z.string().optional(),
+        fileName: z.string().optional(),
+        contentType: z.string().optional()
+      })).parse(args.attachments) : [];
       const result = await client3.createCard(projectId, {
         title,
         columnId: args.columnId,
@@ -5640,7 +5708,30 @@ async function handleToolCall(name, args, deps) {
         assigneeId: args.assigneeId,
         planId: args.planId
       });
-      return { success: true, ...result };
+      if (attachments.length === 0) {
+        return { success: true, ...result };
+      }
+      const cardId = result.card?.id;
+      if (!cardId) {
+        return {
+          success: true,
+          ...result,
+          attachmentWarning: "Card created, but attachments were skipped: no card id was returned to upload against."
+        };
+      }
+      const attachmentResults = await Promise.all(attachments.map(async (file) => {
+        try {
+          const uploaded = await attachFileToCard(client3, cardId, file);
+          return { ok: true, attachment: uploaded.attachment };
+        } catch (err) {
+          return {
+            ok: false,
+            fileName: file.fileName ?? file.filePath ?? "(unnamed)",
+            error: err instanceof Error ? err.message : String(err)
+          };
+        }
+      }));
+      return { success: true, ...result, attachments: attachmentResults };
     }
     case "harmony_update_card": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -5926,37 +6017,12 @@ ${list}
         const cardId2 = z.string().uuid().parse(args.cardId);
         const fileName = args.fileName != null ? z.string().parse(args.fileName) : undefined;
         const contentType = args.contentType != null ? z.string().parse(args.contentType) : undefined;
-        if (filePath) {
-          const bytes = await readFileForUpload(filePath, MAX_ATTACHMENT_SIZE, "attachment");
-          const resolvedName = fileName || basename(filePath);
-          const signed = await client3.requestCardAttachmentUploadUrl(cardId2, {
-            fileName: resolvedName,
-            fileType: contentType,
-            size: bytes.byteLength
-          });
-          await putToSignedUrl(signed.uploadUrl, bytes, contentType || signed.fileType || "application/octet-stream");
-          return await client3.finalizeCardAttachment(cardId2, {
-            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.");
-          }
-          if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
-            throw new Error(`File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`);
-          }
-          return await client3.uploadCardAttachment(cardId2, {
-            fileName,
-            data: base64Data,
-            fileType: contentType
-          });
-        }
-        throw new Error("Provide either filePath or base64Data.");
+        return await attachFileToCard(client3, cardId2, {
+          filePath,
+          base64Data,
+          fileName,
+          contentType
+        });
       }
       const title = args.title != null ? z.string().parse(args.title) : undefined;
       const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"

package/src/server.ts

@@ -221,6 +221,80 @@ async function putToSignedUrl(
   }
 }
 
+/** One card-attachment input: bytes as a local `filePath` (preferred — read
+ * direct-to-storage) or a small `base64Data` blob (requires `fileName`). */
+export interface CardAttachmentInput {
+  filePath?: string;
+  base64Data?: string;
+  fileName?: string;
+  contentType?: string;
+}
+
+/**
+ * Attach one file to an existing card, running the same direct-to-storage
+ * handshake as `harmony_upload` `{target:"card_attachment"}`. Extracted so
+ * `harmony_create_card` can attach reference files (e.g. a prompt screenshot)
+ * at creation time without duplicating the orchestration. Requires an existing
+ * `cardId` — attachment upload is inherently a second step after the card row
+ * exists, so the create path calls this only after `createCard` returns.
+ */
+async function attachFileToCard(
+  client: HarmonyApiClient,
+  cardId: string,
+  file: CardAttachmentInput,
+) {
+  const { filePath, base64Data, fileName, contentType } = file;
+  if (filePath && base64Data) {
+    throw new Error("Provide either filePath or base64Data, not both.");
+  }
+
+  if (filePath) {
+    // Server can read the file → upload direct-to-storage via the handshake
+    // (no base64 through the model context or edge-fn 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.");
+    }
+    if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
+      throw new Error(
+        `File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`,
+      );
+    }
+    return await client.uploadCardAttachment(cardId, {
+      fileName,
+      data: base64Data,
+      fileType: contentType,
+    });
+  }
+
+  throw new Error("Provide either filePath or base64Data.");
+}
+
 /**
  * Dependencies injected into tool handlers.
  * Allows the same handlers to be used by both stdio and remote (HTTP) transports.
@@ -524,7 +598,10 @@ function cleanupMemorySession(cardId: string): void {
 export const TOOLS = {
   // Card operations
   harmony_create_card: {
-    description: "Create a new card in a Kanban column",
+    description:
+      "Create a new card in a Kanban column. Optionally attach reference files " +
+      "(e.g. a screenshot from the prompt) at creation time via `attachments` — " +
+      "the card is created first, then each file is uploaded to it.",
     inputSchema: {
       type: "object",
       properties: {
@@ -550,6 +627,42 @@ export const TOOLS = {
           description:
             "Plan ID to link this card to (optional). Links the card to that plan via its plan_id.",
         },
+        attachments: {
+          type: "array",
+          description:
+            "Optional reference files to attach to the new card (e.g. a screenshot from the prompt). " +
+            "Max 5MB each; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV. Each file's bytes " +
+            "come from `filePath` (absolute local path the server reads, preferred) or `base64Data` " +
+            "(small-file fallback; requires fileName). NOTE: a pasted image only attaches if your " +
+            "harness has written it to a local file you can pass as filePath — a model cannot re-emit " +
+            "pasted image bytes into base64Data. Per-file failures never block card creation; they are " +
+            "reported back in the result's `attachments` array so you can retry via harmony_upload.",
+          items: {
+            type: "object",
+            properties: {
+              filePath: {
+                type: "string",
+                description:
+                  "Absolute path to a local file the server can read. Mutually exclusive with base64Data.",
+              },
+              base64Data: {
+                type: "string",
+                description:
+                  "Base64-encoded bytes (a `data:` URL prefix is accepted and stripped). Requires fileName. Mutually exclusive with filePath.",
+              },
+              fileName: {
+                type: "string",
+                description:
+                  "File name including extension (required with base64Data; else defaults to the filePath basename).",
+              },
+              contentType: {
+                type: "string",
+                description:
+                  "Optional MIME type (inferred from the extension when omitted).",
+              },
+            },
+          },
+        },
       },
       required: ["title"],
     },
@@ -2681,6 +2794,19 @@ async function handleToolCall(
     case "harmony_create_card": {
       const title = z.string().min(1).max(500).parse(args.title);
       const projectId = (args.projectId as string) || getProjectId();
+      const attachments =
+        args.attachments != null
+          ? z
+              .array(
+                z.object({
+                  filePath: z.string().optional(),
+                  base64Data: z.string().optional(),
+                  fileName: z.string().optional(),
+                  contentType: z.string().optional(),
+                }),
+              )
+              .parse(args.attachments)
+          : [];
       const result = await client.createCard(projectId, {
         title,
         columnId: args.columnId as string | undefined,
@@ -2689,7 +2815,40 @@ async function handleToolCall(
         assigneeId: args.assigneeId as string | undefined,
         planId: args.planId as string | undefined,
       });
-      return { success: true, ...result };
+
+      if (attachments.length === 0) {
+        return { success: true, ...result };
+      }
+
+      // Attach reference files (e.g. a prompt screenshot) to the freshly
+      // created card. Attachment upload requires an existing cardId, so this
+      // runs only after createCard returns. A bad attachment must never lose
+      // the card — per-file failures are captured and reported alongside the
+      // successes rather than throwing out the whole create.
+      const cardId = (result.card as { id?: string } | null)?.id;
+      if (!cardId) {
+        return {
+          success: true,
+          ...result,
+          attachmentWarning:
+            "Card created, but attachments were skipped: no card id was returned to upload against.",
+        };
+      }
+      const attachmentResults = await Promise.all(
+        attachments.map(async (file) => {
+          try {
+            const uploaded = await attachFileToCard(client, cardId, file);
+            return { ok: true as const, attachment: uploaded.attachment };
+          } catch (err) {
+            return {
+              ok: false as const,
+              fileName: file.fileName ?? file.filePath ?? "(unnamed)",
+              error: err instanceof Error ? err.message : String(err),
+            };
+          }
+        }),
+      );
+      return { success: true, ...result, attachments: attachmentResults };
     }
 
     case "harmony_update_card": {
@@ -3162,52 +3321,13 @@ async function handleToolCall(
           args.contentType != null
             ? z.string().parse(args.contentType)
             : undefined;
-
-        if (filePath) {
-          // Server can read the file → upload direct-to-storage via the
-          // handshake (no base64 through the model context or edge-fn 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.");
-          }
-          if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
-            throw new Error(
-              `File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`,
-            );
-          }
-          return await client.uploadCardAttachment(cardId, {
-            fileName,
-            data: base64Data,
-            fileType: contentType,
-          });
-        }
-
-        throw new Error("Provide either filePath or base64Data.");
+        // Same handshake as the create-card `attachments` path (shared helper).
+        return await attachFileToCard(client, cardId, {
+          filePath,
+          base64Data,
+          fileName,
+          contentType,
+        });
       }
 
       // target === "artifact"