@gethmy/mcp 2.19.0 → 2.20.1

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"]
@@ -4128,7 +4190,7 @@ var TOOLS = {
     }
   },
   harmony_upload: {
-    description: 'Upload a file in one call. `target: "card_attachment"` attaches a file to a card ' + "(max 5MB; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV) — requires cardId. " + '`target: "artifact"` hosts a self-contained HTML doc (text/html, max 2MB) linked to ' + "exactly one of cardId/planId/workspaceId, rendered in-app in a sandboxed iframe. Provide " + "the bytes as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). " + "Returns the attachment/artifact + a signed URL (artifact: use harmony_share_artifact for a " + "public link). Large files on the hosted MCP server: use harmony_request_upload_url + " + "harmony_finalize_upload instead.",
+    description: 'Upload a file in one call. `target: "card_attachment"` attaches a file to a card ' + "(max 5MB; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV) — requires cardId. " + '`target: "artifact"` hosts a self-contained HTML doc (text/html, max 2MB) linked to ' + "exactly one of cardId/planId/workspaceId, rendered in-app in a sandboxed iframe. Provide " + "the bytes as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). " + "Returns the attachment/artifact. An artifact comes back with TWO URLs, and the difference " + "matters: `app_url` is the durable in-app permalink — this is the one to hand a person, it " + "never expires and requires them to log in as a workspace member — while `signed_url` only " + "renders the document in-app and dies within the hour, so never pass it on. To share with " + "someone OUTSIDE the workspace, mint a public link with harmony_share_artifact. Large files " + "on the hosted MCP server: use harmony_request_upload_url + harmony_finalize_upload instead.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4214,7 +4276,7 @@ var TOOLS = {
     }
   },
   harmony_finalize_upload: {
-    description: "Step 2 of the upload handshake. After PUTting the bytes to the signed uploadUrl, call this " + "with the storagePath to validate and register. The server re-downloads the object and " + "enforces size + content-type (magic-byte sniff, never the declared type) + an optional " + 'sha256 integrity check, deleting and failing on any mismatch. `target: "card_attachment"` ' + '(cardId, storagePath, fileName) or `target: "artifact"` (storagePath + the same one of ' + "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed URL.",
+    description: "Step 2 of the upload handshake. After PUTting the bytes to the signed uploadUrl, call this " + "with the storagePath to validate and register. The server re-downloads the object and " + "enforces size + content-type (magic-byte sniff, never the declared type) + an optional " + 'sha256 integrity check, deleting and failing on any mismatch. `target: "card_attachment"` ' + '(cardId, storagePath, fileName) or `target: "artifact"` (storagePath + the same one of ' + "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed " + "URL; an artifact also carries `app_url`, the durable in-app permalink — hand that one to a " + "person, never the short-lived `signed_url`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4268,7 +4330,7 @@ var TOOLS = {
     }
   },
   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.",
+    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. Only needed for a recipient OUTSIDE the workspace — for a teammate, hand over the `app_url` the upload already returned instead of exposing the document publicly.",
     inputSchema: {
       type: "object",
       properties: {
@@ -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;
@@ -8480,14 +8546,29 @@ ${summary}`);
 
 This project uses Harmony for task management. When working on tasks:
 
+## Agent identity — always identify as yourself
+
+Every \`harmony_start_agent_session\` call passes \`agentIdentifier\` + \`agentName\`. **Use your own
+identity, never a hardcoded one from this file.** AGENTS.md is a cross-runtime convention file, so
+more than one kind of agent will read it; the board shows agents as teammates, and a session
+attributed to the wrong runtime misattributes the work in front of the whole team.
+
+- \`agentIdentifier\` — a stable kebab-case id for the runtime you actually are
+- \`agentName\` — its human-readable name
+
+Known values: \`claude-code\` / "Claude Code", \`codex\` / "OpenAI Codex", \`cursor\` / "Cursor",
+\`claude-desktop\` / "Claude Desktop". If you are a runtime not listed here, use your own name rather
+than borrowing the closest entry.
+
 ## Starting Work on a Card
 
 When given a card reference (e.g., #42 or a card name), follow this workflow:
 
-1. Use \`harmony_get_card_by_short_id\` or \`harmony_search_cards\` to find the card
+1. Use \`harmony_get_card\` or \`harmony_search_cards\` to find the card
 2. Move the card to "In Progress" using \`harmony_move_card\`
 3. Add the "agent" label using \`harmony_add_label_to_card\`
-4. Start a session with \`harmony_start_agent_session\` (agentIdentifier: "codex", agentName: "OpenAI Codex")
+4. Start a session with \`harmony_start_agent_session\`, passing **your own** \`agentIdentifier\` +
+   \`agentName\` (see "Agent identity" above)
 5. Show the card details to the user
 6. Use \`harmony_generate_prompt\` to get guidance, then implement the solution
 7. Update progress periodically with \`harmony_update_agent_progress\`
@@ -8498,7 +8579,8 @@ When given a card reference (e.g., #42 or a card name), follow this workflow:
 Before implementing a plan or feature, check if it maps to an existing Harmony card:
 
 1. Use \`harmony_search_cards\` with keywords from the task description
-2. If a match is found, call \`harmony_start_agent_session\` (agentIdentifier: "claude-code", agentName: "Claude Code", moveToColumn: "In Progress", addLabels: ["agent"])
+2. If a match is found, call \`harmony_start_agent_session\` with **your own** \`agentIdentifier\` +
+   \`agentName\` (see "Agent identity" above), plus \`moveToColumn: "In Progress"\`, \`addLabels: ["agent"]\`
 3. Update progress with \`harmony_update_agent_progress\` at milestones
 4. When done, call \`harmony_end_agent_session\` with status: "completed", moveToColumn: "Review"
 

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"]
@@ -4123,7 +4185,7 @@ var TOOLS = {
     }
   },
   harmony_upload: {
-    description: 'Upload a file in one call. `target: "card_attachment"` attaches a file to a card ' + "(max 5MB; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV) — requires cardId. " + '`target: "artifact"` hosts a self-contained HTML doc (text/html, max 2MB) linked to ' + "exactly one of cardId/planId/workspaceId, rendered in-app in a sandboxed iframe. Provide " + "the bytes as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). " + "Returns the attachment/artifact + a signed URL (artifact: use harmony_share_artifact for a " + "public link). Large files on the hosted MCP server: use harmony_request_upload_url + " + "harmony_finalize_upload instead.",
+    description: 'Upload a file in one call. `target: "card_attachment"` attaches a file to a card ' + "(max 5MB; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV) — requires cardId. " + '`target: "artifact"` hosts a self-contained HTML doc (text/html, max 2MB) linked to ' + "exactly one of cardId/planId/workspaceId, rendered in-app in a sandboxed iframe. Provide " + "the bytes as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). " + "Returns the attachment/artifact. An artifact comes back with TWO URLs, and the difference " + "matters: `app_url` is the durable in-app permalink — this is the one to hand a person, it " + "never expires and requires them to log in as a workspace member — while `signed_url` only " + "renders the document in-app and dies within the hour, so never pass it on. To share with " + "someone OUTSIDE the workspace, mint a public link with harmony_share_artifact. Large files " + "on the hosted MCP server: use harmony_request_upload_url + harmony_finalize_upload instead.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4209,7 +4271,7 @@ var TOOLS = {
     }
   },
   harmony_finalize_upload: {
-    description: "Step 2 of the upload handshake. After PUTting the bytes to the signed uploadUrl, call this " + "with the storagePath to validate and register. The server re-downloads the object and " + "enforces size + content-type (magic-byte sniff, never the declared type) + an optional " + 'sha256 integrity check, deleting and failing on any mismatch. `target: "card_attachment"` ' + '(cardId, storagePath, fileName) or `target: "artifact"` (storagePath + the same one of ' + "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed URL.",
+    description: "Step 2 of the upload handshake. After PUTting the bytes to the signed uploadUrl, call this " + "with the storagePath to validate and register. The server re-downloads the object and " + "enforces size + content-type (magic-byte sniff, never the declared type) + an optional " + 'sha256 integrity check, deleting and failing on any mismatch. `target: "card_attachment"` ' + '(cardId, storagePath, fileName) or `target: "artifact"` (storagePath + the same one of ' + "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed " + "URL; an artifact also carries `app_url`, the durable in-app permalink — hand that one to a " + "person, never the short-lived `signed_url`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4263,7 +4325,7 @@ var TOOLS = {
     }
   },
   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.",
+    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. Only needed for a recipient OUTSIDE the workspace — for a teammate, hand over the `app_url` the upload already returned instead of exposing the document publicly.",
     inputSchema: {
       type: "object",
       properties: {
@@ -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.1",
   "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"],
     },
@@ -892,9 +1005,12 @@ export const TOOLS = {
       '`target: "artifact"` hosts a self-contained HTML doc (text/html, max 2MB) linked to ' +
       "exactly one of cardId/planId/workspaceId, rendered in-app in a sandboxed iframe. Provide " +
       "the bytes as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). " +
-      "Returns the attachment/artifact + a signed URL (artifact: use harmony_share_artifact for a " +
-      "public link). Large files on the hosted MCP server: use harmony_request_upload_url + " +
-      "harmony_finalize_upload instead.",
+      "Returns the attachment/artifact. An artifact comes back with TWO URLs, and the difference " +
+      "matters: `app_url` is the durable in-app permalink — this is the one to hand a person, it " +
+      "never expires and requires them to log in as a workspace member — while `signed_url` only " +
+      "renders the document in-app and dies within the hour, so never pass it on. To share with " +
+      "someone OUTSIDE the workspace, mint a public link with harmony_share_artifact. Large files " +
+      "on the hosted MCP server: use harmony_request_upload_url + harmony_finalize_upload instead.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1006,7 +1122,9 @@ export const TOOLS = {
       "enforces size + content-type (magic-byte sniff, never the declared type) + an optional " +
       'sha256 integrity check, deleting and failing on any mismatch. `target: "card_attachment"` ' +
       '(cardId, storagePath, fileName) or `target: "artifact"` (storagePath + the same one of ' +
-      "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed URL.",
+      "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed " +
+      "URL; an artifact also carries `app_url`, the durable in-app permalink — hand that one to a " +
+      "person, never the short-lived `signed_url`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1069,7 +1187,7 @@ export const TOOLS = {
   },
   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.",
+      "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. Only needed for a recipient OUTSIDE the workspace — for a teammate, hand over the `app_url` the upload already returned instead of exposing the document publicly.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2681,6 +2799,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 +2820,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 +3326,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"

package/src/tui/setup.ts

@@ -515,14 +515,29 @@ async function getAgentFiles(
 
 This project uses Harmony for task management. When working on tasks:
 
+## Agent identity — always identify as yourself
+
+Every \`harmony_start_agent_session\` call passes \`agentIdentifier\` + \`agentName\`. **Use your own
+identity, never a hardcoded one from this file.** AGENTS.md is a cross-runtime convention file, so
+more than one kind of agent will read it; the board shows agents as teammates, and a session
+attributed to the wrong runtime misattributes the work in front of the whole team.
+
+- \`agentIdentifier\` — a stable kebab-case id for the runtime you actually are
+- \`agentName\` — its human-readable name
+
+Known values: \`claude-code\` / "Claude Code", \`codex\` / "OpenAI Codex", \`cursor\` / "Cursor",
+\`claude-desktop\` / "Claude Desktop". If you are a runtime not listed here, use your own name rather
+than borrowing the closest entry.
+
 ## Starting Work on a Card
 
 When given a card reference (e.g., #42 or a card name), follow this workflow:
 
-1. Use \`harmony_get_card_by_short_id\` or \`harmony_search_cards\` to find the card
+1. Use \`harmony_get_card\` or \`harmony_search_cards\` to find the card
 2. Move the card to "In Progress" using \`harmony_move_card\`
 3. Add the "agent" label using \`harmony_add_label_to_card\`
-4. Start a session with \`harmony_start_agent_session\` (agentIdentifier: "codex", agentName: "OpenAI Codex")
+4. Start a session with \`harmony_start_agent_session\`, passing **your own** \`agentIdentifier\` +
+   \`agentName\` (see "Agent identity" above)
 5. Show the card details to the user
 6. Use \`harmony_generate_prompt\` to get guidance, then implement the solution
 7. Update progress periodically with \`harmony_update_agent_progress\`
@@ -533,7 +548,8 @@ When given a card reference (e.g., #42 or a card name), follow this workflow:
 Before implementing a plan or feature, check if it maps to an existing Harmony card:
 
 1. Use \`harmony_search_cards\` with keywords from the task description
-2. If a match is found, call \`harmony_start_agent_session\` (agentIdentifier: "claude-code", agentName: "Claude Code", moveToColumn: "In Progress", addLabels: ["agent"])
+2. If a match is found, call \`harmony_start_agent_session\` with **your own** \`agentIdentifier\` +
+   \`agentName\` (see "Agent identity" above), plus \`moveToColumn: "In Progress"\`, \`addLabels: ["agent"]\`
 3. Update progress with \`harmony_update_agent_progress\` at milestones
 4. When done, call \`harmony_end_agent_session\` with status: "completed", moveToColumn: "Review"