@gethmy/mcp 3.2.0 → 3.3.0

package/README.md

@@ -5,7 +5,7 @@ Claude Code, OpenAI Codex, Cursor, and any MCP client claim cards, report progre
 
 ## Features
 
-- **77 MCP Tools** for full board control, knowledge graph, and workflow plans
+- **79 MCP Tools** for full board control, knowledge graph, and workflow plans
 - **Global Skills** — installable in one command, served from the DB-backed [skill hub](../../docs/skills.md) with auto-update and admin-managed versioning
 - **Knowledge Graph Memory** — Phase 1 surface: hybrid retrieval (vector + lexical + RRF), session-scoped working memory, activity feed. See [docs/memory.md](../../docs/memory.md)
 - **GSD Workflow Plans** - plan/execute/verify/done lifecycle with auto card creation
@@ -89,7 +89,7 @@ If you prefer to configure manually (e.g., in Claude.ai's UI):
 1. Get an API key from [Harmony](https://gethmy.com/user/keys)
 2. In Claude.ai, add a remote MCP server with URL `https://mcp.gethmy.com/mcp`
 3. Set the Authorization header to `Bearer hmy_your_key_here`
-4. All 77 Harmony tools become available in your conversation
+4. All 79 Harmony tools become available in your conversation
 
 **Session management** is automatic - sessions have a 1-hour TTL and are created/renewed transparently.
 

package/dist/cli.js

@@ -1389,7 +1389,6 @@ var AGENT_MILESTONE_LIVENESS_MS = 30 * 60 * 1000;
 var AGENT_SWEEP_DAEMON_MS = 30 * 60 * 1000;
 var AGENT_SWEEP_INTERACTIVE_MS = 2 * 60 * 60 * 1000;
 var AGENT_SWEEP_PAUSED_MS = 4 * 60 * 60 * 1000;
-var SWEPT_SESSION_WRITE_GRACE_MS = 60 * 60 * 1000;
 var ACTIVE_STATUSES = new Set(["working", "blocked", "waiting"]);
 // ../harmony-shared/dist/cardLinks.js
 var LINK_TYPE_INVERSES = {
@@ -2617,6 +2616,9 @@ ${untrustedDataBlock(planContent.trim(), {
   async updatePlaybook(playbookId, updates) {
     return this.request("PATCH", `/playbooks/${playbookId}`, updates);
   }
+  async deletePlaybook(playbookId) {
+    return this.request("DELETE", `/playbooks/${encodeURIComponent(playbookId)}`);
+  }
 }
 var _promptModules = null;
 async function loadPromptModules() {
@@ -2854,6 +2856,36 @@ async function autoEndSession(scope, client3, cardId, status) {
   } catch {}
 }
 
+// src/comment-session.ts
+var RUN_SESSION_CARD_ENV = "HARMONY_AGENT_CARD_ID";
+var RUN_SESSION_ID_ENV = "HARMONY_AGENT_SESSION_ID";
+function readDeclaredRunSession(env = process.env) {
+  const cardId = env[RUN_SESSION_CARD_ENV]?.trim();
+  const agentSessionId = env[RUN_SESSION_ID_ENV]?.trim();
+  if (!cardId || !agentSessionId)
+    return null;
+  return { cardId, agentSessionId };
+}
+function chooseCommentSession(args) {
+  const tracked = args.tracked;
+  if (tracked?.agentSessionId && tracked.scopeId === args.callerScopeId) {
+    return {
+      kind: "session",
+      agentSessionId: tracked.agentSessionId,
+      source: "tracked"
+    };
+  }
+  const declared = args.declared;
+  if (declared && declared.cardId === args.cardId) {
+    return {
+      kind: "session",
+      agentSessionId: declared.agentSessionId,
+      source: "declared"
+    };
+  }
+  return { kind: "sessionless" };
+}
+
 // src/server.ts
 init_config();
 
@@ -3452,6 +3484,51 @@ async function onboardNewUser(params) {
   };
 }
 
+// src/plan-task-link.ts
+function findPlanTask(tasks, taskId) {
+  if (!taskId) {
+    return { ok: false, reason: "No plan task id was given." };
+  }
+  if (!Array.isArray(tasks)) {
+    return {
+      ok: false,
+      reason: "The plan returned no readable criteria list."
+    };
+  }
+  for (const row of tasks) {
+    if (!row || typeof row !== "object")
+      continue;
+    const candidate = row;
+    if (candidate.id === taskId) {
+      return { ok: true, task: candidate };
+    }
+  }
+  return {
+    ok: false,
+    reason: `Plan task ${taskId} is not one of this plan's criteria. ` + `Read the plan with harmony_get_plan and use an id from its \`tasks\`.`
+  };
+}
+function linkedReport(planId, task, newCardId) {
+  const previous = task.card_id ?? null;
+  return {
+    planId,
+    taskId: task.id,
+    linked: true,
+    criterion: task.content ?? null,
+    ...previous && previous !== newCardId ? { replacedCardId: previous } : {}
+  };
+}
+function unlinkedReport(planId, task, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    planId,
+    taskId: task.id,
+    linked: false,
+    criterion: task.content ?? null,
+    error: `The card was created, but the plan criterion still does not point at it: ${message}. ` + `Repair it with harmony_link_plan_task — do not create the card again.`
+  };
+}
+
 // src/playbook-metric-warnings.ts
 function playbookMetricWarnings(agents, steps) {
   if (!Array.isArray(steps))
@@ -3949,12 +4026,13 @@ function optionalNonNegativeNumberArg(raw, field) {
     throw new Error(`${field} must be a non-negative number.`);
   return n;
 }
-function initMemorySession(cardId, agentIdentifier, agentName, agentSessionId) {
+function initMemorySession(cardId, agentIdentifier, agentName, agentSessionId, scopeId) {
   memorySessions.set(cardId, {
     cardId,
     agentIdentifier,
     agentName,
     agentSessionId,
+    scopeId,
     memoryReadCount: 0,
     pendingActions: [],
     allActions: [],
@@ -4066,6 +4144,10 @@ var TOOLS = {
           type: "string",
           description: "Plan ID to link this card to (optional). Links the card to that plan via its plan_id."
         },
+        planTaskId: {
+          type: "string",
+          description: "Id of the plan CRITERION this card is created to fulfil (optional; requires `planId`). " + "Sets both directions at once: the card's plan_id, and the criterion's card_id — the " + "return leg a card outcome needs to reach the plan. Read the ids from harmony_get_plan's " + "`tasks`. A criterion that is not in the named plan refuses the whole call, so no card is " + "created on a false premise; a failure to write the return leg AFTER the card exists " + "keeps the card and reports it in `planTask` instead."
+        },
         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.",
@@ -5543,6 +5625,29 @@ var TOOLS = {
       required: ["planId"]
     }
   },
+  harmony_link_plan_task: {
+    description: "Point a plan CRITERION at the card that fulfils it, and/or set the criterion's status. " + "A plan task is a success criterion, not a work item: `cards.plan_id` says which plan a card " + "belongs to, and this sets the return leg the plan needs to show real progress instead of " + "guessing from board-column names. Use it to repair a link, to re-point a criterion at a " + "different card, or to mark a criterion `completed` once its card actually delivered it. " + "Leave a criterion the card did NOT deliver open — an open criterion is the signal.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        planId: { type: "string", description: "Plan ID owning the criterion" },
+        taskId: {
+          type: "string",
+          description: "Criterion id, from harmony_get_plan's `tasks`. Must belong to `planId`."
+        },
+        cardId: {
+          type: "string",
+          description: "Card that fulfils this criterion. Must live in the plan's own project."
+        },
+        status: {
+          type: "string",
+          enum: ["pending", "in_progress", "completed"],
+          description: "Criterion status. Set `completed` only when the card demonstrably delivered it."
+        }
+      },
+      required: ["planId", "taskId"]
+    }
+  },
   harmony_list_playbook: {
     description: "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, and state. Read-only.",
     inputSchema: {
@@ -5637,6 +5742,19 @@ var TOOLS = {
       required: ["playbookId"]
     }
   },
+  harmony_delete_playbook: {
+    description: "Permanently delete a playbook. IRREVERSIBLE and cascading: its version snapshots and run history are deleted with it, and every card currently running it is unbound — the card stays on the board and keeps its column, but loses its playbook, its pinned version and its stage pointer, so the agent daemon stops treating it as a stage card. Prefer harmony_update_playbook with state='deprecated' unless the playbook should never have existed: a deprecated playbook stays applicable to in-flight cards and is only hidden from new applies. Requires the playbook's creator or a workspace owner/admin — and an ARMED playbook (triggerType 'auto') takes an owner/admin even from its creator, because removing it stops the workspace's automation for everyone. Anyone else is refused and the playbook is left alone. Returns unboundCardCount (the exact number of cards it unbound) and unboundCards (up to 50 of them by id, short_id, title and the stage each one lost).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to delete (UUID)"
+        }
+      },
+      required: ["playbookId"]
+    }
+  },
   harmony_signup: {
     description: "Create a new user account. Returns a JWT session for subsequent authenticated calls. No API key required.",
     inputSchema: {
@@ -5931,28 +6049,58 @@ async function handleToolCall(name, args, deps) {
         fileName: z.string().optional(),
         contentType: z.string().optional()
       })).parse(args.attachments) : [];
+      const planId = args.planId ? z.string().uuid().parse(args.planId) : undefined;
+      const planTaskId = args.planTaskId ? z.string().uuid().parse(args.planTaskId) : undefined;
+      if (planTaskId && !planId) {
+        throw new Error("planTaskId requires planId: no route resolves a plan from a criterion id alone. " + "Pass the plan the criterion belongs to — harmony_get_plan returns both.");
+      }
+      let criterion;
+      if (planTaskId && planId) {
+        const { tasks } = await client3.getPlan(planId);
+        const found = findPlanTask(tasks, planTaskId);
+        if (!found.ok)
+          throw new Error(found.reason);
+        criterion = found.task;
+      }
       const result = await client3.createCard(projectId, {
         title,
         columnId: args.columnId,
         description: args.description,
         priority: args.priority,
         assigneeId: args.assigneeId,
-        planId: args.planId
+        planId
       });
+      const newCardId = result.card?.id;
+      let planTask;
+      if (criterion && planId) {
+        if (!newCardId) {
+          planTask = unlinkedReport(planId, criterion, new Error("no card id was returned to link against"));
+        } else {
+          try {
+            await client3.updatePlanTask(planId, criterion.id, {
+              cardId: newCardId
+            });
+            planTask = linkedReport(planId, criterion, newCardId);
+          } catch (err) {
+            planTask = unlinkedReport(planId, criterion, err);
+          }
+        }
+      }
+      const planTaskField = planTask ? { planTask } : {};
       if (attachments.length === 0) {
-        return { success: true, ...result };
+        return { success: true, ...result, ...planTaskField };
       }
-      const cardId = result.card?.id;
-      if (!cardId) {
+      if (!newCardId) {
         return {
           success: true,
           ...result,
+          ...planTaskField,
           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);
+          const uploaded = await attachFileToCard(client3, newCardId, file);
           return { ok: true, attachment: uploaded.attachment };
         } catch (err) {
           return {
@@ -5962,7 +6110,12 @@ async function handleToolCall(name, args, deps) {
           };
         }
       }));
-      return { success: true, ...result, attachments: attachmentResults };
+      return {
+        success: true,
+        ...result,
+        ...planTaskField,
+        attachments: attachmentResults
+      };
     }
     case "harmony_update_card": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -6446,15 +6599,24 @@ ${list}
       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 agentSessionId = getMemorySession(cardId)?.agentSessionId;
+      const sessionChoice = chooseCommentSession({
+        cardId,
+        tracked: getMemorySession(cardId),
+        callerScopeId: deps.getScopeId?.(),
+        declared: readDeclaredRunSession()
+      });
       const result = await client3.addComment(cardId, body, {
         commentType,
         supersedesId,
         confirmsId,
         replyToId,
-        agentSessionId
+        agentSessionId: sessionChoice.kind === "session" ? sessionChoice.agentSessionId : undefined
       });
-      return { success: true, ...result };
+      return {
+        success: true,
+        ...result,
+        sessionAttribution: sessionChoice.kind === "session" ? sessionChoice.source : "none"
+      };
     }
     case "harmony_get_comments": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -6678,7 +6840,7 @@ ${options}
         scopeId: deps.getScopeId?.()
       });
       const agentSessionId = result.session?.id;
-      initMemorySession(cardId, agentIdentifier, agentName, agentSessionId);
+      initMemorySession(cardId, agentIdentifier, agentName, agentSessionId, deps.getScopeId?.());
       return {
         success: true,
         assignedTo,
@@ -7379,6 +7541,30 @@ ${options}
       const result = await client3.updatePlan(planId, updates);
       return { success: true, plan: result.plan };
     }
+    case "harmony_link_plan_task": {
+      const planId = z.string().uuid().parse(args.planId);
+      const taskId = z.string().uuid().parse(args.taskId);
+      const cardId = args.cardId ? z.string().uuid().parse(args.cardId) : undefined;
+      const status = args.status ? z.enum(["pending", "in_progress", "completed"]).parse(args.status) : undefined;
+      if (!cardId && !status) {
+        throw new Error("Nothing to do: pass cardId, status, or both.");
+      }
+      const { tasks } = await client3.getPlan(planId);
+      const found = findPlanTask(tasks, taskId);
+      if (!found.ok)
+        throw new Error(found.reason);
+      await client3.updatePlanTask(planId, taskId, { cardId, status });
+      return {
+        success: true,
+        planTask: {
+          planId,
+          taskId,
+          criterion: found.task.content ?? null,
+          ...cardId ? linkedReport(planId, found.task, cardId) : { linked: found.task.card_id != null },
+          ...status ? { status } : {}
+        }
+      };
+    }
     case "harmony_advance_plan": {
       const planId = z.string().uuid().parse(args.planId);
       const summary = args.summary;
@@ -7466,6 +7652,16 @@ ${options}
         ...warnings.length > 0 ? { warnings } : {}
       };
     }
+    case "harmony_delete_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client3.deletePlaybook(playbookId);
+      return {
+        success: true,
+        playbook: result.playbook,
+        unboundCardCount: result.unboundCardCount,
+        unboundCards: result.unboundCards
+      };
+    }
     case "harmony_save_card_as_playbook":
       return deprecatedRemovedToolResult("harmony_save_card_as_playbook");
     case "harmony_signup": {
@@ -8643,6 +8839,7 @@ var SAFE_HARMONY_TOOLS = [
   "harmony_create_plan",
   "harmony_update_plan",
   "harmony_advance_plan",
+  "harmony_link_plan_task",
   "harmony_remember",
   "harmony_relate",
   "harmony_update_memory",