@gethmy/mcp 2.4.1 → 2.4.3

package/README.md

@@ -5,7 +5,7 @@ Enables AI coding agents (Claude Code, OpenAI Codex, Cursor) to interact with yo
 
 ## Features
 
-- **61+ MCP Tools** for full board control, knowledge graph, and workflow plans
+- **67 MCP Tools** for full board control, knowledge graph, and workflow plans
 - **Knowledge Graph Memory** - persistent memory with entity types, tiers, scopes, and typed relations
 - **Active Learning** - auto-extracts lessons, solutions, and error patterns from completed work sessions
 - **Context Assembly** - token-budget-aware memory injection into AI prompts
@@ -95,7 +95,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 61+ Harmony tools become available in your conversation
+4. All 67 Harmony tools become available in your conversation
 
 **Session management** is automatic - sessions have a 1-hour TTL and are created/renewed transparently.
 
@@ -324,6 +324,9 @@ Store and retrieve persistent knowledge across sessions. Memories have types, ti
 - `harmony_consolidate_memories` - Cluster similar draft/episode memories and merge into reference entities (dry-run by default)
 - `harmony_backfill_embeddings` - Generate vector embeddings for entities missing them
 - `harmony_backfill_relations` - Retroactively create semantic relations across existing entities
+- `harmony_cleanup_memories` - Bulk cleanup helper: flag stale drafts, dedupe boilerplate, trim low-value entries
+- `harmony_audit_memories` - Surface low-confidence or low-quality memories for human review
+- `harmony_purge_memories` - Hard-delete archived or flagged memories (dry-run by default)
 
 ### Context Debugging
 

package/dist/cli.js

@@ -27094,9 +27094,20 @@ class HarmonyApiClient {
           },
           body: options?.rawBody ?? (body ? JSON.stringify(body) : undefined)
         });
-        const data = await response.json();
+        const text = await response.text();
+        const responseContentType = response.headers.get("content-type") || "";
+        const looksLikeJson = responseContentType.includes("application/json");
+        let data = null;
+        let parseError = null;
+        if (text) {
+          try {
+            data = JSON.parse(text);
+          } catch (err) {
+            parseError = err instanceof Error ? err : new Error(String(err));
+          }
+        }
         if (!response.ok) {
-          const errorMsg = data.error || `API error: ${response.status}`;
+          const errorMsg = data?.error || (looksLikeJson ? null : `API error: ${response.status} (non-JSON response)`) || `API error: ${response.status}`;
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }
@@ -27107,6 +27118,9 @@ class HarmonyApiClient {
           }
           throw lastError;
         }
+        if (parseError) {
+          throw new Error(`API returned ${response.status} with invalid JSON body: ${parseError.message}`);
+        }
         return data;
       } catch (error48) {
         lastError = error48 instanceof Error ? error48 : new Error(String(error48));
@@ -27255,6 +27269,9 @@ class HarmonyApiClient {
   async createLabel(projectId, data) {
     return this.request("POST", "/labels", { projectId, ...data });
   }
+  async deleteLabel(labelId) {
+    return this.request("DELETE", `/labels/${labelId}`);
+  }
   async createSubtask(cardId, title) {
     return this.request("POST", "/subtasks", { cardId, title });
   }
@@ -28074,7 +28091,8 @@ var BOILERPLATE_PATTERNS = [
   /^placeholder/i,
   /^\.\.\.$/,
   /^untitled/i,
-  /^(note|memo|draft)\s*\d*$/i
+  /^(note|memo|draft)\s*\d*$/i,
+  /^task transition:/i
 ];
 function isBoilerplate(title, content) {
   const t = title.trim();
@@ -28122,21 +28140,26 @@ function scoreEntity(entity, relationCount, archiveBelow, deleteBelow, staleDraf
     reasons.push("no relations");
   let content = 0;
   const contentLen = entity.content?.length || 0;
-  if (contentLen >= 80)
-    content += 8;
-  const titleOk = entity.title.trim().length >= 4 && !/^(untitled|draft|note)\b/i.test(entity.title.trim());
-  if (titleOk)
-    content += 4;
-  if (!isBoilerplate(entity.title, entity.content))
-    content += 3;
-  if (contentLen < 80)
-    reasons.push(`thin content (${contentLen} chars)`);
-  if (isBoilerplate(entity.title, entity.content))
+  const boilerplate = isBoilerplate(entity.title, entity.content);
+  if (boilerplate) {
     reasons.push("boilerplate title/content");
+  } else {
+    if (contentLen >= 80)
+      content += 8;
+    const titleOk = entity.title.trim().length >= 4 && !/^(untitled|draft|note)\b/i.test(entity.title.trim());
+    if (titleOk)
+      content += 4;
+    content += 3;
+    if (contentLen < 80)
+      reasons.push(`thin content (${contentLen} chars)`);
+  }
   let tierAgeFit = 15;
   if (entity.memory_tier === "draft" && ageDays > 60 && !entity.promoted_from_id) {
     tierAgeFit = 0;
     reasons.push("stuck draft >60d never promoted");
+  } else if (entity.memory_tier === "draft" && (entity.access_count || 0) === 0 && ageDays > 2) {
+    tierAgeFit = 5;
+    reasons.push("draft >2d with zero access");
   }
   if (entity.promoted_from_id) {
     tierAgeFit = Math.min(15, tierAgeFit + 5);
@@ -28988,6 +29011,30 @@ async function onboardNewUser(params) {
 
 // src/server.ts
 var memorySessions = new Map;
+function parseLabelList(raw) {
+  if (raw === undefined || raw === null)
+    return;
+  if (Array.isArray(raw)) {
+    const arr = raw.filter((v) => typeof v === "string").map((v) => v.trim()).filter((v) => v.length > 0);
+    return arr.length ? arr : undefined;
+  }
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (!trimmed)
+      return;
+    if (trimmed.startsWith("[")) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed) && parsed.every((x) => typeof x === "string")) {
+          const arr = parsed.map((v) => v.trim()).filter((v) => v.length > 0);
+          return arr.length ? arr : undefined;
+        }
+      } catch {}
+    }
+    return [trimmed];
+  }
+  return;
+}
 function initMemorySession(cardId, agentIdentifier, agentName) {
   memorySessions.set(cardId, {
     cardId,
@@ -29265,6 +29312,16 @@ var TOOLS = {
       required: ["name", "color"]
     }
   },
+  harmony_delete_label: {
+    description: "Delete a label from a project. Also removes it from any cards that reference it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        labelId: { type: "string", description: "Label ID to delete" }
+      },
+      required: ["labelId"]
+    }
+  },
   harmony_add_label_to_card: {
     description: "Add a label to a card. Provide labelId directly, or labelName to look up (or auto-create) the label by name.",
     inputSchema: {
@@ -30918,6 +30975,11 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.createLabel(projectId, { name: name2, color });
       return { success: true, ...result };
     }
+    case "harmony_delete_label": {
+      const labelId = exports_external.string().uuid().parse(args.labelId);
+      const result = await client3.deleteLabel(labelId);
+      return { success: true, ...result };
+    }
     case "harmony_add_label_to_card": {
       const cardId = exports_external.string().uuid().parse(args.cardId);
       let labelId = args.labelId ? exports_external.string().uuid().parse(args.labelId) : undefined;
@@ -31053,7 +31115,7 @@ async function handleToolCall(name, args, deps) {
       const agentIdentifier = exports_external.string().min(1).max(100).parse(args.agentIdentifier);
       const agentName = exports_external.string().min(1).max(100).parse(args.agentName);
       const moveToColumn = args.moveToColumn;
-      const addLabels = args.addLabels;
+      const addLabels = parseLabelList(args.addLabels);
       let movedTo = null;
       const labelsAdded = [];
       if (moveToColumn || addLabels?.length) {

package/dist/index.js

@@ -24854,9 +24854,20 @@ class HarmonyApiClient {
           },
           body: options?.rawBody ?? (body ? JSON.stringify(body) : undefined)
         });
-        const data = await response.json();
+        const text = await response.text();
+        const responseContentType = response.headers.get("content-type") || "";
+        const looksLikeJson = responseContentType.includes("application/json");
+        let data = null;
+        let parseError = null;
+        if (text) {
+          try {
+            data = JSON.parse(text);
+          } catch (err) {
+            parseError = err instanceof Error ? err : new Error(String(err));
+          }
+        }
         if (!response.ok) {
-          const errorMsg = data.error || `API error: ${response.status}`;
+          const errorMsg = data?.error || (looksLikeJson ? null : `API error: ${response.status} (non-JSON response)`) || `API error: ${response.status}`;
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }
@@ -24867,6 +24878,9 @@ class HarmonyApiClient {
           }
           throw lastError;
         }
+        if (parseError) {
+          throw new Error(`API returned ${response.status} with invalid JSON body: ${parseError.message}`);
+        }
         return data;
       } catch (error48) {
         lastError = error48 instanceof Error ? error48 : new Error(String(error48));
@@ -25015,6 +25029,9 @@ class HarmonyApiClient {
   async createLabel(projectId, data) {
     return this.request("POST", "/labels", { projectId, ...data });
   }
+  async deleteLabel(labelId) {
+    return this.request("DELETE", `/labels/${labelId}`);
+  }
   async createSubtask(cardId, title) {
     return this.request("POST", "/subtasks", { cardId, title });
   }
@@ -25834,7 +25851,8 @@ var BOILERPLATE_PATTERNS = [
   /^placeholder/i,
   /^\.\.\.$/,
   /^untitled/i,
-  /^(note|memo|draft)\s*\d*$/i
+  /^(note|memo|draft)\s*\d*$/i,
+  /^task transition:/i
 ];
 function isBoilerplate(title, content) {
   const t = title.trim();
@@ -25882,21 +25900,26 @@ function scoreEntity(entity, relationCount, archiveBelow, deleteBelow, staleDraf
     reasons.push("no relations");
   let content = 0;
   const contentLen = entity.content?.length || 0;
-  if (contentLen >= 80)
-    content += 8;
-  const titleOk = entity.title.trim().length >= 4 && !/^(untitled|draft|note)\b/i.test(entity.title.trim());
-  if (titleOk)
-    content += 4;
-  if (!isBoilerplate(entity.title, entity.content))
-    content += 3;
-  if (contentLen < 80)
-    reasons.push(`thin content (${contentLen} chars)`);
-  if (isBoilerplate(entity.title, entity.content))
+  const boilerplate = isBoilerplate(entity.title, entity.content);
+  if (boilerplate) {
     reasons.push("boilerplate title/content");
+  } else {
+    if (contentLen >= 80)
+      content += 8;
+    const titleOk = entity.title.trim().length >= 4 && !/^(untitled|draft|note)\b/i.test(entity.title.trim());
+    if (titleOk)
+      content += 4;
+    content += 3;
+    if (contentLen < 80)
+      reasons.push(`thin content (${contentLen} chars)`);
+  }
   let tierAgeFit = 15;
   if (entity.memory_tier === "draft" && ageDays > 60 && !entity.promoted_from_id) {
     tierAgeFit = 0;
     reasons.push("stuck draft >60d never promoted");
+  } else if (entity.memory_tier === "draft" && (entity.access_count || 0) === 0 && ageDays > 2) {
+    tierAgeFit = 5;
+    reasons.push("draft >2d with zero access");
   }
   if (entity.promoted_from_id) {
     tierAgeFit = Math.min(15, tierAgeFit + 5);
@@ -26748,6 +26771,30 @@ async function onboardNewUser(params) {
 
 // src/server.ts
 var memorySessions = new Map;
+function parseLabelList(raw) {
+  if (raw === undefined || raw === null)
+    return;
+  if (Array.isArray(raw)) {
+    const arr = raw.filter((v) => typeof v === "string").map((v) => v.trim()).filter((v) => v.length > 0);
+    return arr.length ? arr : undefined;
+  }
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (!trimmed)
+      return;
+    if (trimmed.startsWith("[")) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed) && parsed.every((x) => typeof x === "string")) {
+          const arr = parsed.map((v) => v.trim()).filter((v) => v.length > 0);
+          return arr.length ? arr : undefined;
+        }
+      } catch {}
+    }
+    return [trimmed];
+  }
+  return;
+}
 function initMemorySession(cardId, agentIdentifier, agentName) {
   memorySessions.set(cardId, {
     cardId,
@@ -27025,6 +27072,16 @@ var TOOLS = {
       required: ["name", "color"]
     }
   },
+  harmony_delete_label: {
+    description: "Delete a label from a project. Also removes it from any cards that reference it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        labelId: { type: "string", description: "Label ID to delete" }
+      },
+      required: ["labelId"]
+    }
+  },
   harmony_add_label_to_card: {
     description: "Add a label to a card. Provide labelId directly, or labelName to look up (or auto-create) the label by name.",
     inputSchema: {
@@ -28678,6 +28735,11 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.createLabel(projectId, { name: name2, color });
       return { success: true, ...result };
     }
+    case "harmony_delete_label": {
+      const labelId = exports_external.string().uuid().parse(args.labelId);
+      const result = await client3.deleteLabel(labelId);
+      return { success: true, ...result };
+    }
     case "harmony_add_label_to_card": {
       const cardId = exports_external.string().uuid().parse(args.cardId);
       let labelId = args.labelId ? exports_external.string().uuid().parse(args.labelId) : undefined;
@@ -28813,7 +28875,7 @@ async function handleToolCall(name, args, deps) {
       const agentIdentifier = exports_external.string().min(1).max(100).parse(args.agentIdentifier);
       const agentName = exports_external.string().min(1).max(100).parse(args.agentName);
       const moveToColumn = args.moveToColumn;
-      const addLabels = args.addLabels;
+      const addLabels = parseLabelList(args.addLabels);
       let movedTo = null;
       const labelsAdded = [];
       if (moveToColumn || addLabels?.length) {

package/dist/lib/api-client.js

@@ -1612,9 +1612,20 @@ class HarmonyApiClient {
           },
           body: options?.rawBody ?? (body ? JSON.stringify(body) : undefined)
         });
-        const data = await response.json();
+        const text = await response.text();
+        const responseContentType = response.headers.get("content-type") || "";
+        const looksLikeJson = responseContentType.includes("application/json");
+        let data = null;
+        let parseError = null;
+        if (text) {
+          try {
+            data = JSON.parse(text);
+          } catch (err) {
+            parseError = err instanceof Error ? err : new Error(String(err));
+          }
+        }
         if (!response.ok) {
-          const errorMsg = data.error || `API error: ${response.status}`;
+          const errorMsg = data?.error || (looksLikeJson ? null : `API error: ${response.status} (non-JSON response)`) || `API error: ${response.status}`;
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }
@@ -1625,6 +1636,9 @@ class HarmonyApiClient {
           }
           throw lastError;
         }
+        if (parseError) {
+          throw new Error(`API returned ${response.status} with invalid JSON body: ${parseError.message}`);
+        }
         return data;
       } catch (error) {
         lastError = error instanceof Error ? error : new Error(String(error));
@@ -1773,6 +1787,9 @@ class HarmonyApiClient {
   async createLabel(projectId, data) {
     return this.request("POST", "/labels", { projectId, ...data });
   }
+  async deleteLabel(labelId) {
+    return this.request("DELETE", `/labels/${labelId}`);
+  }
   async createSubtask(cardId, title) {
     return this.request("POST", "/subtasks", { cardId, title });
   }

package/package.json

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

package/src/api-client.ts

@@ -176,10 +176,27 @@ export class HarmonyApiClient {
           body: options?.rawBody ?? (body ? JSON.stringify(body) : undefined),
         });
 
-        const data = await response.json();
+        const text = await response.text();
+        const responseContentType = response.headers.get("content-type") || "";
+        const looksLikeJson = responseContentType.includes("application/json");
+
+        let data: ApiResponse | null = null;
+        let parseError: Error | null = null;
+        if (text) {
+          try {
+            data = JSON.parse(text);
+          } catch (err) {
+            parseError = err instanceof Error ? err : new Error(String(err));
+          }
+        }
 
         if (!response.ok) {
-          const errorMsg = data.error || `API error: ${response.status}`;
+          const errorMsg =
+            data?.error ||
+            (looksLikeJson
+              ? null
+              : `API error: ${response.status} (non-JSON response)`) ||
+            `API error: ${response.status}`;
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }
@@ -191,6 +208,12 @@ export class HarmonyApiClient {
           throw lastError;
         }
 
+        if (parseError) {
+          throw new Error(
+            `API returned ${response.status} with invalid JSON body: ${parseError.message}`,
+          );
+        }
+
         return data as T;
       } catch (error) {
         lastError = error instanceof Error ? error : new Error(String(error));
@@ -455,6 +478,10 @@ export class HarmonyApiClient {
     return this.request("POST", "/labels", { projectId, ...data });
   }
 
+  async deleteLabel(labelId: string): Promise<{ success: boolean }> {
+    return this.request("DELETE", `/labels/${labelId}`);
+  }
+
   // ============ SUBTASK OPERATIONS ============
 
   async createSubtask(

package/src/memory-audit.ts

@@ -122,6 +122,9 @@ const BOILERPLATE_PATTERNS = [
   /^\.\.\.$/,
   /^untitled/i,
   /^(note|memo|draft)\s*\d*$/i,
+  // Auto-captured task-transition snapshots from a retired active-learning rule.
+  // No user intent, no access pattern — treat as boilerplate so scoring archives them.
+  /^task transition:/i,
 ];
 
 function isBoilerplate(title: string, content: string): boolean {
@@ -177,18 +180,22 @@ function scoreEntity(
   if (!hasTags) reasons.push("no tags");
   if (!hasRelations) reasons.push("no relations");
 
-  // Content quality (15)
+  // Content quality (15) — boilerplate hard-zeroes the whole band. Auto-captured
+  // noise should never inherit the length/title bonuses it structurally earns.
   let content = 0;
   const contentLen = entity.content?.length || 0;
-  if (contentLen >= 80) content += 8;
-  const titleOk =
-    entity.title.trim().length >= 4 &&
-    !/^(untitled|draft|note)\b/i.test(entity.title.trim());
-  if (titleOk) content += 4;
-  if (!isBoilerplate(entity.title, entity.content)) content += 3;
-  if (contentLen < 80) reasons.push(`thin content (${contentLen} chars)`);
-  if (isBoilerplate(entity.title, entity.content))
+  const boilerplate = isBoilerplate(entity.title, entity.content);
+  if (boilerplate) {
     reasons.push("boilerplate title/content");
+  } else {
+    if (contentLen >= 80) content += 8;
+    const titleOk =
+      entity.title.trim().length >= 4 &&
+      !/^(untitled|draft|note)\b/i.test(entity.title.trim());
+    if (titleOk) content += 4;
+    content += 3;
+    if (contentLen < 80) reasons.push(`thin content (${contentLen} chars)`);
+  }
 
   // Tier-age fit (15)
   let tierAgeFit = 15;
@@ -199,6 +206,15 @@ function scoreEntity(
   ) {
     tierAgeFit = 0;
     reasons.push("stuck draft >60d never promoted");
+  } else if (
+    entity.memory_tier === "draft" &&
+    (entity.access_count || 0) === 0 &&
+    ageDays > 2
+  ) {
+    // Young drafts get a 2-day grace window. After that, zero access means
+    // zero signal — strip the tier-age bonus so useless auto-captures fall to archive.
+    tierAgeFit = 5;
+    reasons.push("draft >2d with zero access");
   }
   if (entity.promoted_from_id) {
     tierAgeFit = Math.min(15, tierAgeFit + 5);

package/src/server.ts

@@ -100,6 +100,45 @@ interface MemorySessionState {
 
 const memorySessions = new Map<string, MemorySessionState>();
 
+/**
+ * Normalize a label-list argument into `string[]`.
+ *
+ * Some MCP callers pass `addLabels` as a JSON-encoded string (e.g. `'["agent"]'`)
+ * instead of a real array. Iterating such a string with `for..of` would yield
+ * individual characters and create one bogus single-char label per character.
+ * This helper coerces the value into a well-formed array and drops empty entries.
+ */
+function parseLabelList(raw: unknown): string[] | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (Array.isArray(raw)) {
+    const arr = raw
+      .filter((v): v is string => typeof v === "string")
+      .map((v) => v.trim())
+      .filter((v) => v.length > 0);
+    return arr.length ? arr : undefined;
+  }
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (!trimmed) return undefined;
+    if (trimmed.startsWith("[")) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (
+          Array.isArray(parsed) &&
+          parsed.every((x) => typeof x === "string")
+        ) {
+          const arr = parsed.map((v) => v.trim()).filter((v) => v.length > 0);
+          return arr.length ? arr : undefined;
+        }
+      } catch {
+        // fall through to single-label fallback
+      }
+    }
+    return [trimmed];
+  }
+  return undefined;
+}
+
 function initMemorySession(
   cardId: string,
   agentIdentifier: string,
@@ -431,6 +470,17 @@ const TOOLS = {
       required: ["name", "color"],
     },
   },
+  harmony_delete_label: {
+    description:
+      "Delete a label from a project. Also removes it from any cards that reference it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        labelId: { type: "string", description: "Label ID to delete" },
+      },
+      required: ["labelId"],
+    },
+  },
   harmony_add_label_to_card: {
     description:
       "Add a label to a card. Provide labelId directly, or labelName to look up (or auto-create) the label by name.",
@@ -2412,6 +2462,12 @@ async function handleToolCall(
       return { success: true, ...result };
     }
 
+    case "harmony_delete_label": {
+      const labelId = z.string().uuid().parse(args.labelId);
+      const result = await client.deleteLabel(labelId);
+      return { success: true, ...result };
+    }
+
     case "harmony_add_label_to_card": {
       const cardId = z.string().uuid().parse(args.cardId);
       let labelId = args.labelId
@@ -2603,7 +2659,7 @@ async function handleToolCall(
         .parse(args.agentIdentifier);
       const agentName = z.string().min(1).max(100).parse(args.agentName);
       const moveToColumn = args.moveToColumn as string | undefined;
-      const addLabels = args.addLabels as string[] | undefined;
+      const addLabels = parseLabelList(args.addLabels);
 
       let movedTo: string | null = null;
       const labelsAdded: string[] = [];