@gethmy/mcp 2.13.0 → 2.13.2

package/dist/cli.js

@@ -1928,6 +1928,10 @@ class HarmonyApiClient {
       qs.set("limit", String(opts.limit));
     if (opts?.offset != null)
       qs.set("offset", String(opts.offset));
+    if (opts?.order != null)
+      qs.set("order", opts.order);
+    if (opts?.commentType != null)
+      qs.set("comment_type", opts.commentType);
     const suffix = qs.toString() ? `?${qs.toString()}` : "";
     return this.request("GET", `/cards/${cardId}/comments${suffix}`);
   }
@@ -2293,7 +2297,8 @@ class HarmonyApiClient {
     });
     try {
       const { comments } = await this.getComments(options.cardId, {
-        limit: 200
+        limit: 200,
+        order: "desc"
       });
       if (Array.isArray(comments) && comments.length > 0) {
         const section = serializeCommentThread(comments, {
@@ -3529,6 +3534,45 @@ function parseLabelList(raw) {
   }
   return;
 }
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function requireStringArg(raw, field, opts = {}) {
+  let value;
+  if (typeof raw === "string")
+    value = raw.trim();
+  else if (typeof raw === "number" || typeof raw === "boolean")
+    value = String(raw);
+  else
+    throw new Error(`${field} is required and must be a string (received ${raw === undefined || raw === null ? "nothing" : typeof raw}).`);
+  if (value.length === 0)
+    throw new Error(`${field} is required and must not be empty.`);
+  if (opts.max && value.length > opts.max)
+    throw new Error(`${field} must be at most ${opts.max} characters (received ${value.length}).`);
+  return value;
+}
+function requireUuidArg(raw, field) {
+  const value = requireStringArg(raw, field);
+  if (!UUID_RE.test(value))
+    throw new Error(`${field} must be a valid UUID (received "${value}").`);
+  return value;
+}
+function optionalPercentArg(raw, field) {
+  if (raw === undefined || raw === null)
+    return;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(n))
+    throw new Error(`${field} must be a number between 0 and 100.`);
+  if (n < 0 || n > 100)
+    throw new Error(`${field} must be between 0 and 100 (received ${n}).`);
+  return n;
+}
+function optionalNonNegativeNumberArg(raw, field) {
+  if (raw === undefined || raw === null)
+    return;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(n) || n < 0)
+    throw new Error(`${field} must be a non-negative number.`);
+  return n;
+}
 function initMemorySession(cardId, agentIdentifier, agentName, agentSessionId) {
   memorySessions.set(cardId, {
     cardId,
@@ -5376,7 +5420,6 @@ function registerHandlers(server, deps) {
     const { name, arguments: args } = request.params;
     const toolArgs = args || {};
     const cardIdArg = toolArgs.cardId;
-    const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     if (cardIdArg && UUID_RE.test(cardIdArg) && deps.isConfigured()) {
       const isAutoStartTrigger = AUTO_START_TRIGGERS.has(name);
       const cv = server.getClientVersion?.();
@@ -6042,9 +6085,11 @@ async function handleToolCall(name, args, deps) {
       return { success: true, ...result };
     }
     case "harmony_start_agent_session": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const agentIdentifier = z.string().min(1).max(100).parse(args.agentIdentifier);
-      const agentName = z.string().min(1).max(100).parse(args.agentName);
+      const cardId = requireUuidArg(args.cardId, "cardId");
+      const agentIdentifier = requireStringArg(args.agentIdentifier, "agentIdentifier", { max: 100 });
+      const agentName = requireStringArg(args.agentName, "agentName", {
+        max: 100
+      });
       const moveToColumn = args.moveToColumn;
       const addLabels = parseLabelList(args.addLabels);
       let movedTo = null;
@@ -6105,7 +6150,7 @@ async function handleToolCall(name, args, deps) {
         agentName,
         status: "working",
         currentTask: args.currentTask,
-        estimatedMinutesRemaining: args.estimatedMinutesRemaining,
+        estimatedMinutesRemaining: optionalNonNegativeNumberArg(args.estimatedMinutesRemaining, "estimatedMinutesRemaining"),
         steerable: args.steerable === true || args.steerable === "true" ? true : undefined
       });
       markExplicit(cardId, {
@@ -6125,10 +6170,12 @@ async function handleToolCall(name, args, deps) {
       };
     }
     case "harmony_update_agent_progress": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const agentIdentifier = z.string().min(1).max(100).parse(args.agentIdentifier);
-      const agentName = z.string().min(1).max(100).parse(args.agentName);
-      const progressPercent = args.progressPercent !== undefined ? z.number().min(0).max(100).parse(args.progressPercent) : undefined;
+      const cardId = requireUuidArg(args.cardId, "cardId");
+      const agentIdentifier = requireStringArg(args.agentIdentifier, "agentIdentifier", { max: 100 });
+      const agentName = requireStringArg(args.agentName, "agentName", {
+        max: 100
+      });
+      const progressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       const callerActions = args.actions;
       const now = new Date().toISOString();
       const callerRecentActions = [
@@ -6153,17 +6200,17 @@ async function handleToolCall(name, args, deps) {
         progressPercent,
         currentTask: args.currentTask,
         blockers: args.blockers,
-        estimatedMinutesRemaining: args.estimatedMinutesRemaining,
+        estimatedMinutesRemaining: optionalNonNegativeNumberArg(args.estimatedMinutesRemaining, "estimatedMinutesRemaining"),
         ...mergedRecentActions && { recentActions: mergedRecentActions },
         ...runActivity.length > 0 && { runActivity }
       });
       return { success: true, midSessionLearnings: 0, ...result };
     }
     case "harmony_end_agent_session": {
-      const cardId = z.string().uuid().parse(args.cardId);
+      const cardId = requireUuidArg(args.cardId, "cardId");
       const moveToColumn = args.moveToColumn;
       const sessionStatus = args.status || "completed";
-      const endProgressPercent = args.progressPercent !== undefined ? z.number().min(0).max(100).parse(args.progressPercent) : undefined;
+      const endProgressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       await flushMemoryActions(client3, cardId);
       cleanupMemorySession(cardId);
       let result = { session: null };

package/dist/index.js

@@ -1923,6 +1923,10 @@ class HarmonyApiClient {
       qs.set("limit", String(opts.limit));
     if (opts?.offset != null)
       qs.set("offset", String(opts.offset));
+    if (opts?.order != null)
+      qs.set("order", opts.order);
+    if (opts?.commentType != null)
+      qs.set("comment_type", opts.commentType);
     const suffix = qs.toString() ? `?${qs.toString()}` : "";
     return this.request("GET", `/cards/${cardId}/comments${suffix}`);
   }
@@ -2288,7 +2292,8 @@ class HarmonyApiClient {
     });
     try {
       const { comments } = await this.getComments(options.cardId, {
-        limit: 200
+        limit: 200,
+        order: "desc"
       });
       if (Array.isArray(comments) && comments.length > 0) {
         const section = serializeCommentThread(comments, {
@@ -3524,6 +3529,45 @@ function parseLabelList(raw) {
   }
   return;
 }
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function requireStringArg(raw, field, opts = {}) {
+  let value;
+  if (typeof raw === "string")
+    value = raw.trim();
+  else if (typeof raw === "number" || typeof raw === "boolean")
+    value = String(raw);
+  else
+    throw new Error(`${field} is required and must be a string (received ${raw === undefined || raw === null ? "nothing" : typeof raw}).`);
+  if (value.length === 0)
+    throw new Error(`${field} is required and must not be empty.`);
+  if (opts.max && value.length > opts.max)
+    throw new Error(`${field} must be at most ${opts.max} characters (received ${value.length}).`);
+  return value;
+}
+function requireUuidArg(raw, field) {
+  const value = requireStringArg(raw, field);
+  if (!UUID_RE.test(value))
+    throw new Error(`${field} must be a valid UUID (received "${value}").`);
+  return value;
+}
+function optionalPercentArg(raw, field) {
+  if (raw === undefined || raw === null)
+    return;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(n))
+    throw new Error(`${field} must be a number between 0 and 100.`);
+  if (n < 0 || n > 100)
+    throw new Error(`${field} must be between 0 and 100 (received ${n}).`);
+  return n;
+}
+function optionalNonNegativeNumberArg(raw, field) {
+  if (raw === undefined || raw === null)
+    return;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(n) || n < 0)
+    throw new Error(`${field} must be a non-negative number.`);
+  return n;
+}
 function initMemorySession(cardId, agentIdentifier, agentName, agentSessionId) {
   memorySessions.set(cardId, {
     cardId,
@@ -5371,7 +5415,6 @@ function registerHandlers(server, deps) {
     const { name, arguments: args } = request.params;
     const toolArgs = args || {};
     const cardIdArg = toolArgs.cardId;
-    const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     if (cardIdArg && UUID_RE.test(cardIdArg) && deps.isConfigured()) {
       const isAutoStartTrigger = AUTO_START_TRIGGERS.has(name);
       const cv = server.getClientVersion?.();
@@ -6037,9 +6080,11 @@ async function handleToolCall(name, args, deps) {
       return { success: true, ...result };
     }
     case "harmony_start_agent_session": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const agentIdentifier = z.string().min(1).max(100).parse(args.agentIdentifier);
-      const agentName = z.string().min(1).max(100).parse(args.agentName);
+      const cardId = requireUuidArg(args.cardId, "cardId");
+      const agentIdentifier = requireStringArg(args.agentIdentifier, "agentIdentifier", { max: 100 });
+      const agentName = requireStringArg(args.agentName, "agentName", {
+        max: 100
+      });
       const moveToColumn = args.moveToColumn;
       const addLabels = parseLabelList(args.addLabels);
       let movedTo = null;
@@ -6100,7 +6145,7 @@ async function handleToolCall(name, args, deps) {
         agentName,
         status: "working",
         currentTask: args.currentTask,
-        estimatedMinutesRemaining: args.estimatedMinutesRemaining,
+        estimatedMinutesRemaining: optionalNonNegativeNumberArg(args.estimatedMinutesRemaining, "estimatedMinutesRemaining"),
         steerable: args.steerable === true || args.steerable === "true" ? true : undefined
       });
       markExplicit(cardId, {
@@ -6120,10 +6165,12 @@ async function handleToolCall(name, args, deps) {
       };
     }
     case "harmony_update_agent_progress": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const agentIdentifier = z.string().min(1).max(100).parse(args.agentIdentifier);
-      const agentName = z.string().min(1).max(100).parse(args.agentName);
-      const progressPercent = args.progressPercent !== undefined ? z.number().min(0).max(100).parse(args.progressPercent) : undefined;
+      const cardId = requireUuidArg(args.cardId, "cardId");
+      const agentIdentifier = requireStringArg(args.agentIdentifier, "agentIdentifier", { max: 100 });
+      const agentName = requireStringArg(args.agentName, "agentName", {
+        max: 100
+      });
+      const progressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       const callerActions = args.actions;
       const now = new Date().toISOString();
       const callerRecentActions = [
@@ -6148,17 +6195,17 @@ async function handleToolCall(name, args, deps) {
         progressPercent,
         currentTask: args.currentTask,
         blockers: args.blockers,
-        estimatedMinutesRemaining: args.estimatedMinutesRemaining,
+        estimatedMinutesRemaining: optionalNonNegativeNumberArg(args.estimatedMinutesRemaining, "estimatedMinutesRemaining"),
         ...mergedRecentActions && { recentActions: mergedRecentActions },
         ...runActivity.length > 0 && { runActivity }
       });
       return { success: true, midSessionLearnings: 0, ...result };
     }
     case "harmony_end_agent_session": {
-      const cardId = z.string().uuid().parse(args.cardId);
+      const cardId = requireUuidArg(args.cardId, "cardId");
       const moveToColumn = args.moveToColumn;
       const sessionStatus = args.status || "completed";
-      const endProgressPercent = args.progressPercent !== undefined ? z.number().min(0).max(100).parse(args.progressPercent) : undefined;
+      const endProgressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       await flushMemoryActions(client3, cardId);
       cleanupMemorySession(cardId);
       let result = { session: null };

package/dist/lib/api-client.js

@@ -1375,6 +1375,10 @@ class HarmonyApiClient {
       qs.set("limit", String(opts.limit));
     if (opts?.offset != null)
       qs.set("offset", String(opts.offset));
+    if (opts?.order != null)
+      qs.set("order", opts.order);
+    if (opts?.commentType != null)
+      qs.set("comment_type", opts.commentType);
     const suffix = qs.toString() ? `?${qs.toString()}` : "";
     return this.request("GET", `/cards/${cardId}/comments${suffix}`);
   }
@@ -1740,7 +1744,8 @@ class HarmonyApiClient {
     });
     try {
       const { comments } = await this.getComments(options.cardId, {
-        limit: 200
+        limit: 200,
+        order: "desc"
       });
       if (Array.isArray(comments) && comments.length > 0) {
         const section = serializeCommentThread(comments, {

package/package.json

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

package/src/api-client.ts

@@ -857,11 +857,25 @@ export class HarmonyApiClient {
 
   async getComments(
     cardId: string,
-    opts?: { limit?: number; offset?: number },
+    opts?: {
+      limit?: number;
+      offset?: number;
+      /**
+       * Created-at sort direction. Default server-side is "asc" (oldest first).
+       * Pass "desc" so a bounded `limit` window pages the NEWEST comments — what
+       * the daemon's handoff and card-context reads need on a chatty card so the
+       * most-recent comments aren't paged out (card #531).
+       */
+      order?: "asc" | "desc";
+      /** Filter to a single `comment_type` (e.g. "decision" for handoffs). */
+      commentType?: string;
+    },
   ): Promise<{ comments: unknown[] }> {
     const qs = new URLSearchParams();
     if (opts?.limit != null) qs.set("limit", String(opts.limit));
     if (opts?.offset != null) qs.set("offset", String(opts.offset));
+    if (opts?.order != null) qs.set("order", opts.order);
+    if (opts?.commentType != null) qs.set("comment_type", opts.commentType);
     const suffix = qs.toString() ? `?${qs.toString()}` : "";
     return this.request("GET", `/cards/${cardId}/comments${suffix}`);
   }
@@ -1734,8 +1748,12 @@ export class HarmonyApiClient {
     // Code, in-app builder) gets the recency-ordered thread + conflict rule.
     // Best-effort — never fail prompt generation on a comments fetch error.
     try {
+      // Newest-first window so a chatty card (>200 comments) keeps the recent
+      // thread instead of paging out to the oldest comments (#531). The
+      // serializer re-sorts oldest→newest, so the rendered order is unchanged.
       const { comments } = await this.getComments(options.cardId, {
         limit: 200,
+        order: "desc",
       });
       if (Array.isArray(comments) && comments.length > 0) {
         const section = serializeCommentThread(comments as Comment[], {

package/src/server.ts

@@ -244,6 +244,86 @@ function parseLabelList(raw: unknown): string[] | undefined {
   return undefined;
 }
 
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Coerce + validate a required string argument from a (possibly lenient) MCP
+ * caller, throwing a clear, field-attributed error on failure.
+ *
+ * The agent-session tools previously parsed these with a bare
+ * `z.string().parse(args.foo)`. When the field was missing or arrived as a
+ * non-string, Zod surfaced an opaque root-level blob —
+ * `[{"expected":"string","received":"undefined","path":[],...}]` — that names
+ * neither the offending field nor the received value. To an agent that reads
+ * as "the tool rejects every argument shape with an `expected string` error"
+ * (card #530). Instead we name the field, report what we got, and (matching
+ * the `parseLabelList` philosophy for quirky clients) accept the
+ * number/boolean values some MCP clients emit by stringifying scalars.
+ */
+function requireStringArg(
+  raw: unknown,
+  field: string,
+  opts: { max?: number } = {},
+): string {
+  let value: string;
+  if (typeof raw === "string") value = raw.trim();
+  else if (typeof raw === "number" || typeof raw === "boolean")
+    value = String(raw);
+  else
+    throw new Error(
+      `${field} is required and must be a string (received ${
+        raw === undefined || raw === null ? "nothing" : typeof raw
+      }).`,
+    );
+  if (value.length === 0)
+    throw new Error(`${field} is required and must not be empty.`);
+  if (opts.max && value.length > opts.max)
+    throw new Error(
+      `${field} must be at most ${opts.max} characters (received ${value.length}).`,
+    );
+  return value;
+}
+
+/** Coerce + validate a required UUID argument with a field-named error. */
+function requireUuidArg(raw: unknown, field: string): string {
+  const value = requireStringArg(raw, field);
+  if (!UUID_RE.test(value))
+    throw new Error(`${field} must be a valid UUID (received "${value}").`);
+  return value;
+}
+
+/**
+ * Coerce an optional 0–100 percentage. Accepts numeric strings (e.g. "50")
+ * because lenient MCP clients stringify scalar arguments; returns `undefined`
+ * when absent and throws a clear, field-named error when out of range.
+ */
+function optionalPercentArg(raw: unknown, field: string): number | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(n))
+    throw new Error(`${field} must be a number between 0 and 100.`);
+  if (n < 0 || n > 100)
+    throw new Error(`${field} must be between 0 and 100 (received ${n}).`);
+  return n;
+}
+
+/**
+ * Coerce an optional non-negative number argument (e.g.
+ * `estimatedMinutesRemaining`). Accepts numeric strings; returns `undefined`
+ * when absent so the field is omitted from the API payload entirely.
+ */
+function optionalNonNegativeNumberArg(
+  raw: unknown,
+  field: string,
+): number | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(n) || n < 0)
+    throw new Error(`${field} must be a non-negative number.`);
+  return n;
+}
+
 function initMemorySession(
   cardId: string,
   agentIdentifier: string,
@@ -2369,8 +2449,6 @@ export function registerHandlers(server: Server, deps: ToolDeps): void {
     // Auto-session pre-hook: track activity on card-related tools
     const toolArgs = args || {};
     const cardIdArg = toolArgs.cardId as string | undefined;
-    const UUID_RE =
-      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     if (cardIdArg && UUID_RE.test(cardIdArg) && deps.isConfigured()) {
       const isAutoStartTrigger = AUTO_START_TRIGGERS.has(name);
       // Resolve MCP client identity per request from the in-scope Server. The
@@ -3356,13 +3434,15 @@ async function handleToolCall(
 
     // Agent context operations
     case "harmony_start_agent_session": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const agentIdentifier = z
-        .string()
-        .min(1)
-        .max(100)
-        .parse(args.agentIdentifier);
-      const agentName = z.string().min(1).max(100).parse(args.agentName);
+      const cardId = requireUuidArg(args.cardId, "cardId");
+      const agentIdentifier = requireStringArg(
+        args.agentIdentifier,
+        "agentIdentifier",
+        { max: 100 },
+      );
+      const agentName = requireStringArg(args.agentName, "agentName", {
+        max: 100,
+      });
       const moveToColumn = args.moveToColumn as string | undefined;
       const addLabels = parseLabelList(args.addLabels);
 
@@ -3449,9 +3529,10 @@ async function handleToolCall(
         agentName,
         status: "working",
         currentTask: args.currentTask as string | undefined,
-        estimatedMinutesRemaining: args.estimatedMinutesRemaining as
-          | number
-          | undefined,
+        estimatedMinutesRemaining: optionalNonNegativeNumberArg(
+          args.estimatedMinutesRemaining,
+          "estimatedMinutesRemaining",
+        ),
         steerable:
           args.steerable === true || args.steerable === "true"
             ? true
@@ -3482,17 +3563,19 @@ async function handleToolCall(
     }
 
     case "harmony_update_agent_progress": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const agentIdentifier = z
-        .string()
-        .min(1)
-        .max(100)
-        .parse(args.agentIdentifier);
-      const agentName = z.string().min(1).max(100).parse(args.agentName);
-      const progressPercent =
-        args.progressPercent !== undefined
-          ? z.number().min(0).max(100).parse(args.progressPercent)
-          : undefined;
+      const cardId = requireUuidArg(args.cardId, "cardId");
+      const agentIdentifier = requireStringArg(
+        args.agentIdentifier,
+        "agentIdentifier",
+        { max: 100 },
+      );
+      const agentName = requireStringArg(args.agentName, "agentName", {
+        max: 100,
+      });
+      const progressPercent = optionalPercentArg(
+        args.progressPercent,
+        "progressPercent",
+      );
       // Convert actions parameter to recentActions format and merge with memory actions
       const callerActions = args.actions as
         | { description: string }[]
@@ -3535,9 +3618,10 @@ async function handleToolCall(
         progressPercent,
         currentTask: args.currentTask as string | undefined,
         blockers: args.blockers as string[] | undefined,
-        estimatedMinutesRemaining: args.estimatedMinutesRemaining as
-          | number
-          | undefined,
+        estimatedMinutesRemaining: optionalNonNegativeNumberArg(
+          args.estimatedMinutesRemaining,
+          "estimatedMinutesRemaining",
+        ),
         ...(mergedRecentActions && { recentActions: mergedRecentActions }),
         ...(runActivity.length > 0 && { runActivity }),
       });
@@ -3547,14 +3631,14 @@ async function handleToolCall(
     }
 
     case "harmony_end_agent_session": {
-      const cardId = z.string().uuid().parse(args.cardId);
+      const cardId = requireUuidArg(args.cardId, "cardId");
       const moveToColumn = args.moveToColumn as string | undefined;
       const sessionStatus =
         (args.status as "completed" | "paused") || "completed";
-      const endProgressPercent =
-        args.progressPercent !== undefined
-          ? z.number().min(0).max(100).parse(args.progressPercent)
-          : undefined;
+      const endProgressPercent = optionalPercentArg(
+        args.progressPercent,
+        "progressPercent",
+      );
 
       // Final flush of any pending memory actions before ending the session
       await flushMemoryActions(client, cardId);