@gethmy/mcp 2.4.4 → 2.4.6

package/dist/cli.js

@@ -27052,16 +27052,28 @@ async function requestWithBearer(apiUrl, bearerToken, method, path, body) {
   return result;
 }
 
+class HarmonyUnauthorizedError extends Error {
+  constructor(message = "Invalid or expired credentials") {
+    super(message);
+    this.name = "HarmonyUnauthorizedError";
+  }
+}
+
 class HarmonyApiClient {
   apiKey;
   apiUrl;
+  onUnauthorized;
   constructor(options) {
     this.apiKey = options?.apiKey ?? getApiKey();
     this.apiUrl = options?.apiUrl ?? getApiUrl();
+    this.onUnauthorized = options?.onUnauthorized;
   }
   getApiUrl() {
     return this.apiUrl;
   }
+  setApiKey(apiKey) {
+    this.apiKey = apiKey;
+  }
   async request(method, path, body, options) {
     await requestSemaphore.acquire();
     try {
@@ -27108,6 +27120,10 @@ class HarmonyApiClient {
         }
         if (!response.ok) {
           const errorMsg = data?.error || (looksLikeJson ? null : `API error: ${response.status} (non-JSON response)`) || `API error: ${response.status}`;
+          if (response.status === 401) {
+            this.onUnauthorized?.();
+            throw new HarmonyUnauthorizedError(errorMsg);
+          }
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }
@@ -27157,6 +27173,10 @@ class HarmonyApiClient {
           } catch {
             errorMsg = text || `API error: ${response.status}`;
           }
+          if (response.status === 401) {
+            this.onUnauthorized?.();
+            throw new HarmonyUnauthorizedError(errorMsg);
+          }
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }
@@ -28088,23 +28108,25 @@ var BATCH_SIZE = 100;
 var CONCURRENCY_LIMIT = 5;
 var BOILERPLATE_PATTERNS = [
   /^todo:?$/i,
-  /^placeholder/i,
+  /^placeholder(\s+\d+|:)?$/i,
   /^\.\.\.$/,
-  /^untitled/i,
-  /^(note|memo|draft)\s*\d*$/i,
+  /^untitled(\s+\d+|:)?$/i,
+  /^(note|memo|draft)\s+\d+$/i,
   /^task transition:/i
 ];
-function isBoilerplate(title, content) {
+function isBoilerplateTitle(title) {
   const t = title.trim();
-  const c = content.trim();
-  if (c.length === 0)
-    return true;
   for (const pat of BOILERPLATE_PATTERNS) {
     if (pat.test(t))
       return true;
   }
   return false;
 }
+function isBoilerplate(title, content) {
+  if (content.trim().length === 0)
+    return true;
+  return isBoilerplateTitle(title);
+}
 function scoreEntity(entity, relationCount, archiveBelow, deleteBelow, staleDraftAgeDays) {
   const now = Date.now();
   const ageDays = (now - Date.parse(entity.created_at)) / MS_PER_DAY;
@@ -28186,10 +28208,11 @@ function scoreEntity(entity, relationCount, archiveBelow, deleteBelow, staleDraf
     legacy = true;
     legacyReasons.push("no graph presence");
   }
+  const boilerplateTitle = isBoilerplateTitle(entity.title);
   let bucket;
-  if (boilerplate && deleteBelow > 0) {
+  if (boilerplateTitle && deleteBelow > 0) {
     bucket = "delete";
-    reasons.push("boilerplate override");
+    reasons.push("boilerplate title override");
   } else if (score < deleteBelow)
     bucket = "delete";
   else if (score < archiveBelow)

package/dist/index.js

@@ -24812,16 +24812,28 @@ async function requestWithBearer(apiUrl, bearerToken, method, path, body) {
   return result;
 }
 
+class HarmonyUnauthorizedError extends Error {
+  constructor(message = "Invalid or expired credentials") {
+    super(message);
+    this.name = "HarmonyUnauthorizedError";
+  }
+}
+
 class HarmonyApiClient {
   apiKey;
   apiUrl;
+  onUnauthorized;
   constructor(options) {
     this.apiKey = options?.apiKey ?? getApiKey();
     this.apiUrl = options?.apiUrl ?? getApiUrl();
+    this.onUnauthorized = options?.onUnauthorized;
   }
   getApiUrl() {
     return this.apiUrl;
   }
+  setApiKey(apiKey) {
+    this.apiKey = apiKey;
+  }
   async request(method, path, body, options) {
     await requestSemaphore.acquire();
     try {
@@ -24868,6 +24880,10 @@ class HarmonyApiClient {
         }
         if (!response.ok) {
           const errorMsg = data?.error || (looksLikeJson ? null : `API error: ${response.status} (non-JSON response)`) || `API error: ${response.status}`;
+          if (response.status === 401) {
+            this.onUnauthorized?.();
+            throw new HarmonyUnauthorizedError(errorMsg);
+          }
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }
@@ -24917,6 +24933,10 @@ class HarmonyApiClient {
           } catch {
             errorMsg = text || `API error: ${response.status}`;
           }
+          if (response.status === 401) {
+            this.onUnauthorized?.();
+            throw new HarmonyUnauthorizedError(errorMsg);
+          }
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }
@@ -25848,23 +25868,25 @@ var BATCH_SIZE = 100;
 var CONCURRENCY_LIMIT = 5;
 var BOILERPLATE_PATTERNS = [
   /^todo:?$/i,
-  /^placeholder/i,
+  /^placeholder(\s+\d+|:)?$/i,
   /^\.\.\.$/,
-  /^untitled/i,
-  /^(note|memo|draft)\s*\d*$/i,
+  /^untitled(\s+\d+|:)?$/i,
+  /^(note|memo|draft)\s+\d+$/i,
   /^task transition:/i
 ];
-function isBoilerplate(title, content) {
+function isBoilerplateTitle(title) {
   const t = title.trim();
-  const c = content.trim();
-  if (c.length === 0)
-    return true;
   for (const pat of BOILERPLATE_PATTERNS) {
     if (pat.test(t))
       return true;
   }
   return false;
 }
+function isBoilerplate(title, content) {
+  if (content.trim().length === 0)
+    return true;
+  return isBoilerplateTitle(title);
+}
 function scoreEntity(entity, relationCount, archiveBelow, deleteBelow, staleDraftAgeDays) {
   const now = Date.now();
   const ageDays = (now - Date.parse(entity.created_at)) / MS_PER_DAY;
@@ -25946,10 +25968,11 @@ function scoreEntity(entity, relationCount, archiveBelow, deleteBelow, staleDraf
     legacy = true;
     legacyReasons.push("no graph presence");
   }
+  const boilerplateTitle = isBoilerplateTitle(entity.title);
   let bucket;
-  if (boilerplate && deleteBelow > 0) {
+  if (boilerplateTitle && deleteBelow > 0) {
     bucket = "delete";
-    reasons.push("boilerplate override");
+    reasons.push("boilerplate title override");
   } else if (score < deleteBelow)
     bucket = "delete";
   else if (score < archiveBelow)

package/dist/lib/api-client.js

@@ -1570,16 +1570,28 @@ async function requestWithBearer(apiUrl, bearerToken, method, path, body) {
   return result;
 }
 
+class HarmonyUnauthorizedError extends Error {
+  constructor(message = "Invalid or expired credentials") {
+    super(message);
+    this.name = "HarmonyUnauthorizedError";
+  }
+}
+
 class HarmonyApiClient {
   apiKey;
   apiUrl;
+  onUnauthorized;
   constructor(options) {
     this.apiKey = options?.apiKey ?? getApiKey();
     this.apiUrl = options?.apiUrl ?? getApiUrl();
+    this.onUnauthorized = options?.onUnauthorized;
   }
   getApiUrl() {
     return this.apiUrl;
   }
+  setApiKey(apiKey) {
+    this.apiKey = apiKey;
+  }
   async request(method, path, body, options) {
     await requestSemaphore.acquire();
     try {
@@ -1626,6 +1638,10 @@ class HarmonyApiClient {
         }
         if (!response.ok) {
           const errorMsg = data?.error || (looksLikeJson ? null : `API error: ${response.status} (non-JSON response)`) || `API error: ${response.status}`;
+          if (response.status === 401) {
+            this.onUnauthorized?.();
+            throw new HarmonyUnauthorizedError(errorMsg);
+          }
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }
@@ -1675,6 +1691,10 @@ class HarmonyApiClient {
           } catch {
             errorMsg = text || `API error: ${response.status}`;
           }
+          if (response.status === 401) {
+            this.onUnauthorized?.();
+            throw new HarmonyUnauthorizedError(errorMsg);
+          }
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }
@@ -2136,5 +2156,6 @@ export {
   resetClient,
   requestWithBearer,
   getClient,
+  HarmonyUnauthorizedError,
   HarmonyApiClient
 };

package/package.json

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

package/src/__tests__/memory-audit.test.ts

@@ -312,7 +312,89 @@ describe("runMemoryAudit", () => {
     });
     expect(report.summary.delete).toBe(1);
     expect(deletedIds).toContain("promoted-junk");
-    expect(report.lowest[0].reasons).toContain("boilerplate override");
+    expect(report.lowest[0].reasons).toContain("boilerplate title override");
+  });
+
+  test("legitimate titles starting with boilerplate-prefix words are NOT deleted", async () => {
+    // Regression test for the over-broad regex bug. Pre-fix patterns matched
+    // any title starting with "Placeholder", "Untitled", "Note", etc. After
+    // tightening, only exact boilerplate forms (with optional digit suffix
+    // or colon) match — real titles survive.
+    const { client, deletedIds } = makeMockClient(
+      [
+        {
+          id: "legit-placeholder",
+          type: "pattern",
+          title: "Placeholder pattern in React Suspense",
+          content:
+            "Use React.Suspense with a fallback component as the placeholder pattern for streaming SSR.",
+          confidence: 0.9,
+          memory_tier: "reference",
+          access_count: 12,
+          last_accessed_at: daysAgo(1),
+          created_at: daysAgo(60),
+          tags: ["react", "ssr"],
+          embedding: [0.1],
+        },
+        {
+          id: "legit-untitled",
+          type: "context",
+          title: "UntitledMaster.fig — design source for the homepage",
+          content:
+            "Reference Figma file containing master components for landing page assets.",
+          confidence: 0.85,
+          memory_tier: "reference",
+          access_count: 8,
+          last_accessed_at: daysAgo(2),
+          created_at: daysAgo(45),
+          tags: ["design"],
+          embedding: [0.1],
+        },
+        {
+          id: "legit-note",
+          type: "context",
+          title: "Note: schema migration order matters",
+          content: "Always run 0042 before 0043 because of FK dependency.",
+          confidence: 0.8,
+          memory_tier: "reference",
+          access_count: 5,
+          last_accessed_at: daysAgo(3),
+          created_at: daysAgo(30),
+          tags: ["db"],
+          embedding: [0.1],
+        },
+      ],
+      { "legit-placeholder": 3, "legit-untitled": 2, "legit-note": 1 },
+    );
+
+    const report = await runMemoryAudit(client, "ws-1", undefined, {
+      dryRun: false,
+    });
+    expect(deletedIds).toHaveLength(0);
+    expect(report.summary.delete).toBe(0);
+  });
+
+  test("empty-content draft with real title is NOT delete-bucketed", async () => {
+    // Users sometimes save a draft with title only and fill content later.
+    // The override is title-only, so empty content alone must not delete.
+    const { client, deletedIds } = makeMockClient([
+      {
+        id: "draft-empty-body",
+        type: "decision",
+        title: "Decision: skip Q3 launch",
+        content: "",
+        confidence: 0.7,
+        memory_tier: "draft",
+        access_count: 1,
+        last_accessed_at: daysAgo(1),
+        created_at: daysAgo(2),
+        tags: ["q3"],
+        embedding: null,
+      },
+    ]);
+
+    await runMemoryAudit(client, "ws-1", undefined, { dryRun: false });
+    expect(deletedIds).not.toContain("draft-empty-body");
   });
 
   test("boilerplate override respects deleteBelow=0 escape hatch", async () => {

package/src/api-client.ts

@@ -112,19 +112,43 @@ export async function requestWithBearer<T = unknown>(
   return result as T;
 }
 
+// Sentinel thrown when the API rejects the bearer/api-key with HTTP 401.
+// Lets the MCP transport layer turn it into an HTTP 401 + WWW-Authenticate
+// challenge so OAuth clients can refresh, instead of burying it inside a
+// JSON-RPC tool error envelope.
+export class HarmonyUnauthorizedError extends Error {
+  constructor(message = "Invalid or expired credentials") {
+    super(message);
+    this.name = "HarmonyUnauthorizedError";
+  }
+}
+
 export class HarmonyApiClient {
   private apiKey: string;
   private apiUrl: string;
+  private onUnauthorized?: () => void;
 
-  constructor(options?: { apiKey?: string; apiUrl?: string }) {
+  constructor(options?: {
+    apiKey?: string;
+    apiUrl?: string;
+    onUnauthorized?: () => void;
+  }) {
     this.apiKey = options?.apiKey ?? getApiKey();
     this.apiUrl = options?.apiUrl ?? getApiUrl();
+    this.onUnauthorized = options?.onUnauthorized;
   }
 
   getApiUrl(): string {
     return this.apiUrl;
   }
 
+  // Lets the MCP session swap in a freshly refreshed OAuth access token
+  // without recreating the client. Called from remote.ts when the incoming
+  // Bearer header differs from the cached token.
+  setApiKey(apiKey: string): void {
+    this.apiKey = apiKey;
+  }
+
   private async request<T>(
     method: string,
     path: string,
@@ -197,6 +221,13 @@ export class HarmonyApiClient {
               ? null
               : `API error: ${response.status} (non-JSON response)`) ||
             `API error: ${response.status}`;
+          // 401: token rejected by harmony-api. Don't retry — surface a typed
+          // error so the MCP transport layer can issue an HTTP 401 challenge
+          // and trigger the client's OAuth refresh flow.
+          if (response.status === 401) {
+            this.onUnauthorized?.();
+            throw new HarmonyUnauthorizedError(errorMsg);
+          }
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }
@@ -259,6 +290,10 @@ export class HarmonyApiClient {
           } catch {
             errorMsg = text || `API error: ${response.status}`;
           }
+          if (response.status === 401) {
+            this.onUnauthorized?.();
+            throw new HarmonyUnauthorizedError(errorMsg);
+          }
           if (!isRetryableError(null, response.status)) {
             throw new Error(errorMsg);
           }

package/src/memory-audit.ts

@@ -116,27 +116,45 @@ export interface AuditReport {
   healthReport: string;
 }
 
+// Patterns must stay in sync with:
+//   supabase/functions/_shared/memory-boilerplate.ts (edge function guard)
+//   supabase/migrations/*_harden_memory_cleanup.sql  (cron sweeper)
+//
+// End-anchored where possible to avoid matching legitimate titles like
+// "Placeholder pattern in React" or "Untitled.fig reference". The retired
+// mid-session extractor's "Task transition: ..." prefix is the one open-ended
+// pattern — it was never a user-chosen format.
 const BOILERPLATE_PATTERNS = [
   /^todo:?$/i,
-  /^placeholder/i,
+  /^placeholder(\s+\d+|:)?$/i,
   /^\.\.\.$/,
-  /^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.
+  /^untitled(\s+\d+|:)?$/i,
+  /^(note|memo|draft)\s+\d+$/i,
   /^task transition:/i,
 ];
 
-function isBoilerplate(title: string, content: string): boolean {
+/**
+ * Title-only check. Used by the audit override — should not delete an entry
+ * just because its content is empty (may be a draft the user hasn't finished).
+ */
+function isBoilerplateTitle(title: string): boolean {
   const t = title.trim();
-  const c = content.trim();
-  if (c.length === 0) return true;
   for (const pat of BOILERPLATE_PATTERNS) {
     if (pat.test(t)) return true;
   }
   return false;
 }
 
+/**
+ * Stricter check used by the content-quality scoring band. Empty content is
+ * "boilerplate" for scoring — an empty memory contributes nothing regardless
+ * of title — but does not on its own trigger the delete-bucket override.
+ */
+function isBoilerplate(title: string, content: string): boolean {
+  if (content.trim().length === 0) return true;
+  return isBoilerplateTitle(title);
+}
+
 function scoreEntity(
   entity: AuditEntity,
   relationCount: number,
@@ -253,16 +271,18 @@ function scoreEntity(
     legacyReasons.push("no graph presence");
   }
 
-  // Bucket — boilerplate is a one-way door to delete. High access counts on
-  // noise titles signal re-read churn (recall/dedup loops), not genuine reuse;
-  // letting confidence + tier + decay drag the composite score back into
-  // "keep" leaves promoted-to-reference junk untouched. Override scoring,
-  // except when deleteBelow=0 (the "no deletions" escape hatch) — in that
-  // mode boilerplate falls through to archive.
+  // Bucket — boilerplate TITLE is a one-way door to delete. High access
+  // counts on noise titles signal re-read churn (recall/dedup loops), not
+  // genuine reuse; letting confidence + tier + decay drag the composite
+  // score back into "keep" leaves promoted-to-reference junk untouched.
+  // Override scoring, except when deleteBelow=0 (the "no deletions" escape
+  // hatch). Title-only on purpose: an empty-content entry with a real title
+  // may be a draft; the user should see it in the audit, not lose it.
+  const boilerplateTitle = isBoilerplateTitle(entity.title);
   let bucket: AuditBucket;
-  if (boilerplate && deleteBelow > 0) {
+  if (boilerplateTitle && deleteBelow > 0) {
     bucket = "delete";
-    reasons.push("boilerplate override");
+    reasons.push("boilerplate title override");
   } else if (score < deleteBelow) bucket = "delete";
   else if (score < archiveBelow) bucket = "archive";
   else if (score < 70) bucket = "review";

package/src/remote.ts

@@ -90,10 +90,16 @@ async function resolveWorkspaceForLegacyKey(
 interface McpSession {
   transport: WebStandardStreamableHTTPServerTransport;
   server: Server;
+  client: HarmonyApiClient;
   apiKey: string;
   activeWorkspaceId: string | null;
   activeProjectId: string | null;
   createdAt: number;
+  // Set by HarmonyApiClient.onUnauthorized when the API rejects the cached
+  // token mid-session. The HTTP layer reads this after transport.handleRequest
+  // returns and converts the response to an HTTP 401 challenge so the OAuth
+  // client refreshes instead of caching a JSON-RPC error forever.
+  unauthorized: boolean;
 }
 
 const sessions = new Map<string, McpSession>();
@@ -124,18 +130,38 @@ function createSession(apiKey: string, keyInfo: TokenInfo): McpSession {
     { capabilities: { tools: {}, resources: {} } },
   );
 
+  // unauthorized flag lives on a mutable holder so the HarmonyApiClient
+  // callback can flip it without a circular reference between the client and
+  // the session struct it lives on.
+  const authState = { unauthorized: false };
+
+  // Create per-session API client. onUnauthorized fires when harmony-api
+  // returns 401 — we mark the session so the HTTP layer can surface a real
+  // 401 + WWW-Authenticate challenge to the OAuth client.
+  const client = new HarmonyApiClient({
+    apiKey,
+    apiUrl: HARMONY_API_URL,
+    onUnauthorized: () => {
+      authState.unauthorized = true;
+    },
+  });
+
   const session: McpSession = {
     transport,
     server,
+    client,
     apiKey,
     activeWorkspaceId: keyInfo.workspaceId,
     activeProjectId: null,
     createdAt: Date.now(),
+    get unauthorized() {
+      return authState.unauthorized;
+    },
+    set unauthorized(v: boolean) {
+      authState.unauthorized = v;
+    },
   };
 
-  // Create per-session deps
-  const client = new HarmonyApiClient({ apiKey, apiUrl: HARMONY_API_URL });
-
   const deps: ToolDeps = {
     getClient: () => client,
     isConfigured: () => true,
@@ -224,6 +250,16 @@ function unauthenticatedResponse(): Response {
   );
 }
 
+// Evict a session and tear down its transport. Used when an OAuth token
+// rotates or is revoked mid-session — we don't want to keep a zombie session
+// around with a stale cached api key.
+function evictSession(sessionId: string): void {
+  const session = sessions.get(sessionId);
+  if (!session) return;
+  sessions.delete(sessionId);
+  session.transport.close().catch(() => {});
+}
+
 // MCP endpoint - handles POST (JSON-RPC), GET (SSE), DELETE (session close).
 // Mounted on both `/mcp` and `/` so clients that registered the bare host as
 // their server URL still reach the OAuth challenge instead of a 404.
@@ -243,9 +279,33 @@ const handleMcpRequest = async (c: import("hono").Context) => {
   const sessionId = c.req.header("Mcp-Session-Id");
 
   if (sessionId && sessions.has(sessionId)) {
-    // Existing session - forward request
     const session = sessions.get(sessionId)!;
-    return session.transport.handleRequest(c.req.raw);
+
+    // Hot-swap the cached token if the OAuth client just refreshed. Without
+    // this the session would keep using the stale access token forever and
+    // every tool call after refresh would 401 — the bug that motivated this
+    // patch.
+    if (session.apiKey !== apiKey) {
+      session.apiKey = apiKey;
+      session.client.setApiKey(apiKey);
+    }
+
+    // Reset the per-request 401 latch before handing off to the transport.
+    session.unauthorized = false;
+
+    const response = await session.transport.handleRequest(c.req.raw);
+
+    // If a tool call hit 401 against harmony-api, the api-client tripped the
+    // unauthorized flag. Evict the session and return an HTTP 401 +
+    // WWW-Authenticate so the client triggers a refresh — instead of burying
+    // the auth failure inside a JSON-RPC error envelope the client can't act
+    // on.
+    if (session.unauthorized) {
+      evictSession(sessionId);
+      return unauthenticatedResponse();
+    }
+
+    return response;
   }
 
   if (method === "POST") {
@@ -272,8 +332,17 @@ const handleMcpRequest = async (c: import("hono").Context) => {
       origOnSessionInitialized?.(sid);
     };
 
-    // Handle the initialize request
-    return session.transport.handleRequest(c.req.raw);
+    const response = await session.transport.handleRequest(c.req.raw);
+
+    // Same 401-latch check as the existing-session branch — covers the case
+    // where the *initialize* call itself triggers an API request that 401s
+    // (e.g., revoked-during-handshake).
+    if (session.unauthorized && session.transport.sessionId) {
+      evictSession(session.transport.sessionId);
+      return unauthenticatedResponse();
+    }
+
+    return response;
   }
 
   // GET or DELETE without a valid session