@gethmy/mcp 2.20.0 → 2.20.1

package/dist/cli.js

@@ -4190,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: {
@@ -4276,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: {
@@ -4330,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: {
@@ -8546,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\`
@@ -8564,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

@@ -4185,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: {
@@ -4271,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: {
@@ -4325,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: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.20.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

@@ -1005,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: {
@@ -1119,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: {
@@ -1182,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: {

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"