@gethmy/mcp 2.13.3 → 2.14.0

package/dist/index.js

@@ -1452,6 +1452,8 @@ function serializeCommentThread(comments, options = {}) {
     const tags = [];
     if (c.edited_at)
       tags.push("edited");
+    if (c.reply_to_id)
+      tags.push(`reply to ${ref(c.reply_to_id)}`);
     if (c.supersedes_id)
       tags.push(`supersedes ${ref(c.supersedes_id)}`);
     if (c.confirms_id)
@@ -1863,6 +1865,12 @@ class HarmonyApiClient {
   async getCardExternalLinks(cardId) {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
+  async addExternalLink(cardId, url, title) {
+    return this.request("POST", `/cards/${cardId}/external-links`, {
+      url,
+      title
+    });
+  }
   async uploadArtifact(data) {
     return this.request("POST", "/artifacts", data);
   }
@@ -1914,6 +1922,7 @@ class HarmonyApiClient {
       commentType: opts?.commentType,
       supersedesId: opts?.supersedesId,
       confirmsId: opts?.confirmsId,
+      replyToId: opts?.replyToId,
       agentSessionId: opts?.agentSessionId
     });
   }
@@ -2366,12 +2375,6 @@ ${planContent.trim()}`;
   async updatePlaybook(playbookId, updates) {
     return this.request("PATCH", `/playbooks/${playbookId}`, updates);
   }
-  async runPlaybook(playbookId) {
-    return this.request("POST", `/playbooks/${playbookId}/run`);
-  }
-  async savePlaybookFromCard(data) {
-    return this.request("POST", "/playbooks/from-card", data);
-  }
 }
 var _promptModules = null;
 async function loadPromptModules() {
@@ -3235,7 +3238,7 @@ Start work on a Harmony card. Card reference: $ARGUMENTS
 ## 1. Find & Fetch Card
 
 Parse the reference and fetch the card:
-- \`#42\` or \`42\` → \`harmony_get_card_by_short_id\` with \`shortId: 42\`
+- \`#42\` or \`42\` → \`harmony_get_card\` with \`shortId: 42\`
 - UUID → \`harmony_get_card\` with \`cardId\`
 - Name/text → \`harmony_search_cards\` with \`query\`
 
@@ -3289,7 +3292,7 @@ If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
 
 ## Key Tools Reference
 
-**Cards:** \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\`, \`harmony_create_card\`, \`harmony_update_card\`, \`harmony_move_card\`, \`harmony_delete_card\`, \`harmony_assign_card\`
+**Cards:** \`harmony_get_card\` (by \`cardId\`, \`shortId\`, or \`shortIds\`), \`harmony_search_cards\`, \`harmony_create_card\`, \`harmony_update_card\`, \`harmony_move_card\`, \`harmony_delete_card\`, \`harmony_assign_card\`
 
 **Subtasks:** \`harmony_create_subtask\`, \`harmony_toggle_subtask\`, \`harmony_delete_subtask\`
 
@@ -3483,6 +3486,37 @@ function requireExactlyOneScope(scope) {
     throw new Error("Provide exactly one of cardId, planId, or workspaceId.");
   }
 }
+var DEPRECATED_TOOL_ALIASES = {
+  harmony_get_card_by_short_id: "harmony_get_card",
+  harmony_bulk_get_cards: "harmony_get_card",
+  harmony_upload_artifact: "harmony_upload",
+  harmony_upload_card_attachment: "harmony_upload",
+  harmony_request_artifact_upload_url: "harmony_request_upload_url",
+  harmony_request_card_attachment_upload_url: "harmony_request_upload_url",
+  harmony_finalize_artifact: "harmony_finalize_upload",
+  harmony_finalize_card_attachment: "harmony_finalize_upload"
+};
+var _warnedDeprecatedTools = new Set;
+function warnDeprecatedTool(oldName) {
+  if (_warnedDeprecatedTools.has(oldName))
+    return;
+  _warnedDeprecatedTools.add(oldName);
+  const replacement = DEPRECATED_TOOL_ALIASES[oldName];
+  console.error(`[harmony-mcp] Tool "${oldName}" is deprecated (still accepted) — ` + `use "${replacement}" instead. The old name is no longer advertised and ` + `will be removed in a future major version.`);
+}
+var DEPRECATED_REMOVED_TOOLS = {
+  harmony_run_playbook: "Playbooks are stage models run by the board and agent daemon as a card moves through their stages — there is no server-side macro to trigger. This tool no longer runs anything.",
+  harmony_save_card_as_playbook: "The steps_version=1 automation macro was removed. Build a stage playbook with harmony_create_playbook instead."
+};
+var _warnedRemovedTools = new Set;
+function deprecatedRemovedToolResult(name) {
+  const message = DEPRECATED_REMOVED_TOOLS[name];
+  if (!_warnedRemovedTools.has(name)) {
+    _warnedRemovedTools.add(name);
+    console.error(`[harmony-mcp] Tool "${name}" is deprecated and no longer functional — ${message}`);
+  }
+  return { success: false, deprecated: true, message };
+}
 var SIGNED_UPLOAD_TIMEOUT_MS = 30000;
 async function putToSignedUrl(uploadUrl, bytes, contentType) {
   let res;
@@ -3810,44 +3844,29 @@ var TOOLS = {
     }
   },
   harmony_get_card: {
-    description: "Get detailed information about a specific card by UUID",
+    description: "Fetch one or many cards. Provide exactly one of: `cardId` (UUID, full detail), " + "`shortId` (e.g. 42, full detail), or `shortIds` (array, max 100 — compact " + "summaries: id, shortId, title, column, priority, assignee, labels, archived, " + "plus any short ids not found). `shortId`/`shortIds` need project context. " + "Prefer one `shortIds` call over repeated single fetches for multiple cards.",
     inputSchema: {
       type: "object",
       properties: {
-        cardId: { type: "string", description: "Card UUID" }
-      },
-      required: ["cardId"]
-    }
-  },
-  harmony_get_card_by_short_id: {
-    description: "Get a card by its short ID (e.g., #42) within a project",
-    inputSchema: {
-      type: "object",
-      properties: {
-        projectId: {
+        cardId: {
           type: "string",
-          description: "Project ID (optional if context set)"
+          description: "Card UUID — full detail for one card."
         },
         shortId: {
           type: "number",
-          description: "Short ID number (e.g., 42 for card #42)"
-        }
-      },
-      required: ["shortId"]
-    }
-  },
-  harmony_bulk_get_cards: {
-    description: "Fetch multiple cards by short id in one call. Returns compact summaries " + "(id, shortId, title, column, priority, assignee, labels, archived) plus " + "any short ids not found. Requires project context. Prefer this over " + "repeated harmony_get_card_by_short_id when referencing multiple cards.",
-    inputSchema: {
-      type: "object",
-      properties: {
+          description: "Short ID (e.g. 42 for card #42) — full detail, project-scoped."
+        },
         shortIds: {
           type: "array",
           items: { type: "number" },
-          description: "Card short ids, e.g. [400, 401, 402]. Max 100 per call."
+          description: "Short IDs, e.g. [400, 401, 402] — compact summaries in one call. Max 100."
+        },
+        projectId: {
+          type: "string",
+          description: "Project ID for shortId/shortIds (optional if context set)."
         }
       },
-      required: ["shortIds"]
+      required: []
     }
   },
   harmony_bulk_archive_cards: {
@@ -4002,174 +4021,144 @@ var TOOLS = {
       required: ["cardId"]
     }
   },
-  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). 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.",
+  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.",
     inputSchema: {
       type: "object",
       properties: {
-        cardId: { type: "string", description: "Card UUID" },
+        target: {
+          type: "string",
+          enum: ["card_attachment", "artifact"],
+          description: "What to upload: a card file attachment or a hosted HTML artifact."
+        },
+        cardId: {
+          type: "string",
+          description: "Card UUID. Required for card_attachment; one of cardId/planId/workspaceId for artifact."
+        },
+        planId: {
+          type: "string",
+          description: "Plan UUID (artifact only — link the artifact to a plan)."
+        },
+        workspaceId: {
+          type: "string",
+          description: "Workspace UUID (artifact only — standalone artifact)."
+        },
         filePath: {
           type: "string",
-          description: "Absolute path to a local file the MCP server process can read. Mutually exclusive with base64Data."
+          description: "Absolute path to a local file the server can read. Mutually exclusive with base64Data."
         },
         base64Data: {
           type: "string",
-          description: "Base64-encoded file bytes (a `data:` URL prefix is accepted and stripped). Requires fileName. Mutually exclusive with filePath."
+          description: "Base64-encoded bytes (a `data:` URL prefix is accepted and stripped). Mutually exclusive with filePath."
         },
         fileName: {
           type: "string",
-          description: "File name including extension (e.g. 'screenshot.png'). Required with base64Data; defaults to the basename of filePath otherwise."
+          description: "File name including extension (card_attachment: required with base64Data, else defaults to the filePath basename)."
+        },
+        title: {
+          type: "string",
+          description: "Artifact display title (defaults to the file basename)."
         },
         contentType: {
           type: "string",
-          description: "Optional MIME type (e.g. 'image/png'). Inferred from the file extension when omitted."
+          description: "Optional MIME type (card_attachment; inferred from the extension when omitted)."
         }
       },
-      required: ["cardId"]
+      required: ["target"]
     }
   },
-  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.",
+  harmony_request_upload_url: {
+    description: "Step 1 of the large-file / hosted-MCP upload handshake (use when the server can't read " + 'local disk). Mints a one-shot signed Storage upload URL. `target: "card_attachment"` ' + '(requires cardId, fileName, size; max 5MB) or `target: "artifact"` (one of ' + "cardId/planId/workspaceId; text/html, max 2MB). Returns { uploadUrl, token, storagePath, " + "[fileType] }. Then PUT the raw bytes to uploadUrl (no bytes through the model context) and " + "call harmony_finalize_upload with the storagePath.",
     inputSchema: {
       type: "object",
       properties: {
-        cardId: { type: "string", description: "Card UUID" },
-        fileName: {
+        target: {
           type: "string",
-          description: "File name including extension (e.g. 'screenshot.png')."
+          enum: ["card_attachment", "artifact"],
+          description: "What to upload: a card file attachment or a hosted HTML artifact."
         },
-        fileType: {
+        cardId: {
           type: "string",
-          description: "Optional MIME type (e.g. 'image/png'). Inferred from the file extension when omitted."
+          description: "Card UUID. Required for card_attachment; one of cardId/planId/workspaceId for artifact."
         },
-        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: {
+        planId: { type: "string", description: "Plan UUID (artifact only)." },
+        workspaceId: {
           type: "string",
-          description: "The storagePath returned by harmony_request_card_attachment_upload_url."
+          description: "Workspace UUID (artifact only)."
         },
         fileName: {
           type: "string",
-          description: "File name including extension (e.g. 'screenshot.png')."
+          description: "File name including extension (required for card_attachment)."
         },
+        title: { type: "string", description: "Artifact display title." },
         fileType: {
           type: "string",
-          description: "Optional MIME type; inferred from the extension when omitted."
+          description: "card_attachment MIME type (inferred from the extension when omitted)."
         },
-        sha256: {
+        contentType: {
           type: "string",
-          description: "Optional hex SHA-256 of the uploaded bytes; verified against the stored object."
+          description: "artifact MIME type; only 'text/html' is accepted (the default)."
         },
         size: {
           type: "number",
-          description: "Optional byte size (advisory; re-validated server-side)."
+          description: "File size in bytes (rejected early if over the target's limit)."
         }
       },
-      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`.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        cardId: { type: "string", description: "Card UUID" }
-      },
-      required: ["cardId"]
+      required: ["target"]
     }
   },
-  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 — 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.",
+  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.",
     inputSchema: {
       type: "object",
       properties: {
-        title: {
+        target: {
           type: "string",
-          description: "Display title (defaults to the file basename)."
+          enum: ["card_attachment", "artifact"],
+          description: "What to finalize: a card file attachment or a hosted HTML artifact."
         },
-        cardId: { type: "string", description: "Link to this card (UUID)." },
-        planId: { type: "string", description: "Link to this plan (UUID)." },
-        workspaceId: {
+        storagePath: {
           type: "string",
-          description: "Attach to this workspace as a standalone artifact (UUID)."
+          description: "The storagePath returned by harmony_request_upload_url."
         },
-        filePath: {
+        cardId: {
           type: "string",
-          description: "Absolute path to a local .html file the MCP server process can read. Mutually exclusive with base64Data."
+          description: "Card UUID. Required for card_attachment; scope for artifact."
         },
-        base64Data: {
+        planId: { type: "string", description: "Plan UUID (artifact only)." },
+        workspaceId: {
           type: "string",
-          description: "Base64-encoded HTML bytes (a `data:` URL prefix is accepted and stripped). Mutually exclusive with filePath."
-        }
-      },
-      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: {
+          description: "Workspace UUID (artifact only)."
+        },
+        fileName: {
           type: "string",
-          description: "Display title (defaults to the file basename at finalize)."
+          description: "File name including extension (required for card_attachment)."
         },
-        cardId: { type: "string", description: "Link to this card (UUID)." },
-        planId: { type: "string", description: "Link to this plan (UUID)." },
-        workspaceId: {
+        title: { type: "string", description: "Artifact display title." },
+        fileType: {
           type: "string",
-          description: "Attach to this workspace as a standalone artifact (UUID)."
+          description: "card_attachment MIME type; inferred from the extension when omitted."
         },
-        contentType: {
+        sha256: {
           type: "string",
-          description: "MIME type; only 'text/html' is accepted (the default)."
+          description: "Optional hex SHA-256 of the uploaded bytes; verified against the stored object."
         },
         size: {
           type: "number",
-          description: "File size in bytes (rejected early if over 2MB)."
+          description: "Optional byte size (advisory; re-validated server-side)."
         }
       },
-      required: []
+      required: ["target", "storagePath"]
     }
   },
-  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.",
+  harmony_classify_card: {
+    description: "Classify a card with the LLM classifier: sets `intent` (plan/think/implement/review), `complexity_score` (0-10), `model_tier` (simple/advanced/research), stamps `classified_at`, and applies the type label (feature/bug/idea). Call right after creating a card to classify it in-flow. Idempotent; never touches the user-owned `model_override`.",
     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)."
-        }
+        cardId: { type: "string", description: "Card UUID" }
       },
-      required: ["storagePath"]
+      required: ["cardId"]
     }
   },
   harmony_share_artifact: {
@@ -4199,6 +4188,27 @@ var TOOLS = {
       required: ["cardId"]
     }
   },
+  harmony_add_external_link: {
+    description: "Attach an external reference URL (e.g. a PR/MR link, doc, or dashboard) to a card. Durable — survives description edits. Use this in addition to writing the PR link into the description.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: {
+          type: "string",
+          description: "Card UUID"
+        },
+        url: {
+          type: "string",
+          description: "The URL to attach"
+        },
+        title: {
+          type: "string",
+          description: "Optional human-readable title for the link"
+        }
+      },
+      required: ["cardId", "url"]
+    }
+  },
   harmony_create_subtask: {
     description: "Create a subtask on a card",
     inputSchema: {
@@ -4250,7 +4260,7 @@ var TOOLS = {
     }
   },
   harmony_add_comment: {
-    description: "Post a comment on a card as the agent. Use this to converse with the human in the open: report progress, ask a question, record a decision, or note a finding — instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. When the thread conflicts, prefer the latest comment unless a later one confirms an earlier finding; cite the comment id(s) you relied on.",
+    description: "Post a comment on a card as the agent — converse with the human in the open: report progress, ask a question, record a decision, or note a finding, instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. To answer an open question, reply to it with replyToId.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4276,6 +4286,10 @@ var TOOLS = {
         confirmsId: {
           type: "string",
           description: "Comment id this comment reaffirms"
+        },
+        replyToId: {
+          type: "string",
+          description: "Comment id this is a one-level reply to. To answer an open question, reply to it. If you also set supersedesId/confirmsId, it must equal replyToId."
         }
       },
       required: ["cardId", "body"]
@@ -4747,7 +4761,7 @@ var TOOLS = {
         limit: { type: "number", description: "Max results (default: 20)" },
         top_k: {
           type: "number",
-          description: "After Park rescoring (relevance × recency × importance per plan §6), keep this many top entries. Defaults to `limit`. Useful when you want to over-fetch (large `limit`) so the rescorer has more candidates and then trim to a tight top-k."
+          description: "After rescoring (relevance × recency × importance), keep this many top entries. Defaults to `limit`. Over-fetch with a large `limit` then trim to a tight top-k."
         },
         budget_tokens: {
           type: "number",
@@ -4862,7 +4876,7 @@ var TOOLS = {
     }
   },
   harmony_suggest_relations: {
-    description: "Suggest existing memory entities that look related to a given entity, using the same hybrid vector+FTS similarity as recall (card #281). Read-only: it NEVER creates relations — it only proposes candidates for a caller (human/agent) to relate explicitly via harmony_relate. Use to surface 'these look related — link?' candidates that would activate graph-walk retrieval.",
+    description: "Suggest existing memory entities that look related to a given entity, using the same hybrid vector+FTS similarity as recall. Read-only: NEVER creates relations — only proposes candidates to relate explicitly via harmony_relate. Surfaces 'these look related — link?' candidates that would activate graph-walk retrieval.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5146,7 +5160,7 @@ var TOOLS = {
     }
   },
   harmony_list_playbook: {
-    description: "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, steps_version, and state. Read-only.",
+    description: "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, and state. Read-only.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5168,21 +5182,8 @@ var TOOLS = {
       required: ["playbookId"]
     }
   },
-  harmony_run_playbook: {
-    description: "Run a playbook server-side and return the finalized run. Only legacy automation playbooks (steps_version 1) are runnable; stage playbooks (steps_version 2) are rejected. The server drives every step to completion.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        playbookId: {
-          type: "string",
-          description: "Playbook ID to run (UUID)"
-        }
-      },
-      required: ["playbookId"]
-    }
-  },
   harmony_create_playbook: {
-    description: "Create a new playbook in a workspace. Default steps_version 1 is a legacy automation macro (an array of tool steps); steps_version 2 is the Method stage model (an array of stage objects).",
+    description: "Create a new playbook (a reusable process definition) in a workspace. A playbook is an ordered set of stages bound to board columns, run by people and the agent daemon as a card moves through them.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5192,14 +5193,9 @@ var TOOLS = {
         },
         name: { type: "string", description: "Playbook name" },
         description: { type: "string", description: "Playbook description" },
-        stepsVersion: {
-          type: "number",
-          enum: [1, 2],
-          description: "1 = automation macro (tool steps), 2 = Method stage model (stage objects). Default 1."
-        },
         steps: {
           type: "array",
-          description: "Steps (steps_version 1: tool-step objects) or stages (steps_version 2: stage objects).",
+          description: "The playbook's ordered stage objects.",
           items: { type: "object" }
         }
       },
@@ -5219,7 +5215,7 @@ var TOOLS = {
         description: { type: "string", description: "New description" },
         steps: {
           type: "array",
-          description: "New steps (v1) or stages (v2) array.",
+          description: "New ordered stage objects.",
           items: { type: "object" }
         },
         enabled: {
@@ -5235,20 +5231,6 @@ var TOOLS = {
       required: ["playbookId"]
     }
   },
-  harmony_save_card_as_playbook: {
-    description: "Save an existing card as a new steps_version 1 (automation) playbook, seeding one create-card step from the card. Returns the created playbook.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        cardId: { type: "string", description: "Card ID to template (UUID)" },
-        name: {
-          type: "string",
-          description: "Name for the new playbook (defaults to the card title)"
-        }
-      },
-      required: ["cardId"]
-    }
-  },
   harmony_signup: {
     description: "Create a new user account. Returns a JWT session for subsequent authenticated calls. No API key required.",
     inputSchema: {
@@ -5648,23 +5630,33 @@ async function handleToolCall(name, args, deps) {
       });
       return { success: true, ...result, count: result.cards.length };
     }
+    case "harmony_get_card_by_short_id":
+    case "harmony_bulk_get_cards":
     case "harmony_get_card": {
+      if (name !== "harmony_get_card")
+        warnDeprecatedTool(name);
+      const hasShortIds = args.shortIds != null;
+      const hasShortId = args.shortId != null;
+      const hasCardId = args.cardId != null;
+      if ([hasShortIds, hasShortId, hasCardId].filter(Boolean).length !== 1) {
+        throw new Error("Provide exactly one of: cardId (UUID), shortId (number), or shortIds (number[]).");
+      }
+      if (hasShortIds) {
+        const shortIds = z.array(z.number().int().positive()).min(1).max(100).parse(args.shortIds);
+        const projectId = getProjectId();
+        const result2 = await client3.bulkGetCards(projectId, shortIds);
+        return { success: true, ...result2 };
+      }
+      if (hasShortId) {
+        const shortId = z.number().int().positive().parse(args.shortId);
+        const projectId = args.projectId || getProjectId();
+        const result2 = await client3.getCardByShortId(projectId, shortId);
+        return { success: true, ...result2 };
+      }
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client3.getCard(cardId);
       return { success: true, ...result };
     }
-    case "harmony_get_card_by_short_id": {
-      const shortId = z.number().int().positive().parse(args.shortId);
-      const projectId = args.projectId || getProjectId();
-      const result = await client3.getCardByShortId(projectId, shortId);
-      return { success: true, ...result };
-    }
-    case "harmony_bulk_get_cards": {
-      const shortIds = z.array(z.number().int().positive()).min(1).max(100).parse(args.shortIds);
-      const projectId = getProjectId();
-      const result = await client3.bulkGetCards(projectId, shortIds);
-      return { success: true, ...result };
-    }
     case "harmony_bulk_archive_cards": {
       const shortIds = z.array(z.number().int().positive()).min(1).max(100).parse(args.shortIds);
       const projectId = getProjectId();
@@ -5764,58 +5756,58 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.getCardAttachments(cardId);
       return result;
     }
-    case "harmony_upload_card_attachment": {
-      const cardId = z.string().uuid().parse(args.cardId);
+    case "harmony_upload_card_attachment":
+    case "harmony_upload_artifact":
+    case "harmony_upload": {
+      if (name !== "harmony_upload")
+        warnDeprecatedTool(name);
+      const target = name === "harmony_upload_card_attachment" ? "card_attachment" : name === "harmony_upload_artifact" ? "artifact" : z.enum(["card_attachment", "artifact"]).parse(args.target);
       const filePath = args.filePath != null ? z.string().parse(args.filePath) : undefined;
       const base64Data = args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
-      const fileName = args.fileName != null ? z.string().parse(args.fileName) : undefined;
-      const contentType = args.contentType != null ? z.string().parse(args.contentType) : undefined;
       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 (target === "card_attachment") {
+        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 (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.`);
+        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
+          });
         }
-        return await client3.uploadCardAttachment(cardId, {
-          fileName,
-          data: base64Data,
-          fileType: contentType
-        });
+        throw new Error("Provide either filePath or base64Data.");
       }
-      throw new Error("Provide either filePath or base64Data.");
-    }
-    case "harmony_upload_artifact": {
       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 filePath = args.filePath != null ? z.string().parse(args.filePath) : undefined;
-      const base64Data = args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
-      if (filePath && base64Data) {
-        throw new Error("Provide either filePath or base64Data, not both.");
-      }
       if (filePath) {
         const bytes = await readFileForUpload(filePath, MAX_ARTIFACT_SIZE, "artifact");
         const resolvedTitle = title || basename(filePath);
@@ -5840,7 +5832,7 @@ async function handleToolCall(name, args, deps) {
       }
       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.`);
+          throw new Error(`Artifact is over the 2MB limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`);
         }
         return await client3.uploadArtifact({
           title,
@@ -5852,7 +5844,26 @@ async function handleToolCall(name, args, deps) {
       }
       throw new Error("Provide either filePath or base64Data.");
     }
-    case "harmony_request_artifact_upload_url": {
+    case "harmony_request_artifact_upload_url":
+    case "harmony_request_card_attachment_upload_url":
+    case "harmony_request_upload_url": {
+      if (name !== "harmony_request_upload_url")
+        warnDeprecatedTool(name);
+      const target = name === "harmony_request_card_attachment_upload_url" ? "card_attachment" : name === "harmony_request_artifact_upload_url" ? "artifact" : z.enum(["card_attachment", "artifact"]).parse(args.target);
+      if (target === "card_attachment") {
+        const cardId2 = 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 size2 = z.number().positive().parse(args.size);
+        if (size2 > MAX_ATTACHMENT_SIZE) {
+          throw new Error(`Declared size ${size2} bytes is over the ${MAX_ATTACHMENT_SIZE}-byte (5MB) attachment limit.`);
+        }
+        return await client3.requestCardAttachmentUploadUrl(cardId2, {
+          fileName,
+          fileType,
+          size: size2
+        });
+      }
       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;
@@ -5872,8 +5883,27 @@ async function handleToolCall(name, args, deps) {
         size
       });
     }
-    case "harmony_finalize_artifact": {
+    case "harmony_finalize_artifact":
+    case "harmony_finalize_card_attachment":
+    case "harmony_finalize_upload": {
+      if (name !== "harmony_finalize_upload")
+        warnDeprecatedTool(name);
+      const target = name === "harmony_finalize_card_attachment" ? "card_attachment" : name === "harmony_finalize_artifact" ? "artifact" : z.enum(["card_attachment", "artifact"]).parse(args.target);
       const storagePath = z.string().parse(args.storagePath);
+      if (target === "card_attachment") {
+        const cardId2 = 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 sha2562 = args.sha256 != null ? z.string().parse(args.sha256) : undefined;
+        const size2 = args.size != null ? z.number().positive().parse(args.size) : undefined;
+        return await client3.finalizeCardAttachment(cardId2, {
+          storagePath,
+          fileName,
+          fileType,
+          sha256: sha2562,
+          size: size2
+        });
+      }
       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;
@@ -5891,35 +5921,6 @@ async function handleToolCall(name, args, deps) {
         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 client3.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 client3.finalizeCardAttachment(cardId, {
-        storagePath,
-        fileName,
-        fileType,
-        sha256,
-        size
-      });
-    }
     case "harmony_share_artifact": {
       const artifactId = z.string().uuid().parse(args.artifactId);
       const expiresInDays = args.expiresInDays != null ? z.number().positive().parse(args.expiresInDays) : undefined;
@@ -5932,6 +5933,13 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.getCardExternalLinks(cardId);
       return result;
     }
+    case "harmony_add_external_link": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const url = z.string().min(1).max(2048).parse(args.url);
+      const title = args.title ? z.string().max(200).parse(args.title) : undefined;
+      const result = await client3.addExternalLink(cardId, url, title);
+      return { success: true, ...result };
+    }
     case "harmony_classify_card": {
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client3.classifyCard(cardId);
@@ -5985,10 +5993,12 @@ async function handleToolCall(name, args, deps) {
       ]).parse(args.commentType) : undefined;
       const supersedesId = args.supersedesId !== undefined ? z.string().uuid().parse(args.supersedesId) : undefined;
       const confirmsId = args.confirmsId !== undefined ? z.string().uuid().parse(args.confirmsId) : undefined;
+      const replyToId = args.replyToId !== undefined ? z.string().uuid().parse(args.replyToId) : undefined;
       const result = await client3.addComment(cardId, body, {
         commentType,
         supersedesId,
-        confirmsId
+        confirmsId,
+        replyToId
       });
       return { success: true, ...result };
     }
@@ -6848,21 +6858,16 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.getPlaybook(playbookId);
       return { success: true, playbook: result.playbook, runs: result.runs };
     }
-    case "harmony_run_playbook": {
-      const playbookId = z.string().uuid().parse(args.playbookId);
-      const result = await client3.runPlaybook(playbookId);
-      return { success: true, run: result.run };
-    }
+    case "harmony_run_playbook":
+      return deprecatedRemovedToolResult("harmony_run_playbook");
     case "harmony_create_playbook": {
       const workspaceId = args.workspaceId || getWorkspaceId();
       const name2 = z.string().min(1).max(200).parse(args.name);
-      const stepsVersion = args.stepsVersion !== undefined ? z.union([z.literal(1), z.literal(2)]).parse(args.stepsVersion) : undefined;
       const result = await client3.createPlaybook({
         workspaceId,
         name: name2,
         description: args.description,
-        steps: args.steps,
-        stepsVersion
+        steps: args.steps
       });
       return { success: true, playbook: result.playbook };
     }
@@ -6877,14 +6882,8 @@ async function handleToolCall(name, args, deps) {
       });
       return { success: true, playbook: result.playbook };
     }
-    case "harmony_save_card_as_playbook": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const result = await client3.savePlaybookFromCard({
-        cardId,
-        name: args.name
-      });
-      return { success: true, playbook: result.playbook };
-    }
+    case "harmony_save_card_as_playbook":
+      return deprecatedRemovedToolResult("harmony_save_card_as_playbook");
     case "harmony_signup": {
       const email = z.string().email().max(254).parse(args.email);
       const password = z.string().min(8).max(128).parse(args.password);