@gethmy/mcp 2.4.3 → 2.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.4.3",
+  "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

@@ -282,6 +282,148 @@ describe("runMemoryAudit", () => {
     ).toBe(0.25);
   });
 
+  test("boilerplate override forces delete bucket regardless of confidence/access/tier", async () => {
+    // The exact failure mode that motivated this override: legacy task-transition
+    // entries promoted to reference tier with confidence=1.0 and high access_count
+    // were scoring ~80 and surviving in "keep". Verify the override demotes them.
+    const { client, deletedIds } = makeMockClient(
+      [
+        {
+          id: "promoted-junk",
+          type: "context",
+          title: "Task transition: legacy auto-extracted noise",
+          content:
+            "Agent transitioned tasks. Previous: doing X. Current: doing Y. Progress: 100%.",
+          confidence: 1.0,
+          memory_tier: "reference",
+          access_count: 91,
+          last_accessed_at: daysAgo(0),
+          created_at: daysAgo(29),
+          tags: ["auto-extracted", "task-transition", "mid-session"],
+          embedding: [0.1],
+          promoted_from_id: "orig-junk",
+        },
+      ],
+      { "promoted-junk": 2 },
+    );
+
+    const report = await runMemoryAudit(client, "ws-1", undefined, {
+      dryRun: false,
+    });
+    expect(report.summary.delete).toBe(1);
+    expect(deletedIds).toContain("promoted-junk");
+    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 () => {
+    // deleteBelow=0 is a "no deletions, audit-only" knob. Boilerplate must
+    // honor it — operators should be able to inspect findings without losing
+    // data on the same call.
+    const { client, deletedIds } = makeMockClient([
+      {
+        id: "boilerplate-protected",
+        type: "context",
+        title: "Task transition: would normally delete",
+        content: "noise content",
+        confidence: 1.0,
+        memory_tier: "reference",
+        access_count: 50,
+        last_accessed_at: daysAgo(0),
+        created_at: daysAgo(20),
+        tags: ["x"],
+        embedding: [0.1],
+      },
+    ]);
+
+    await runMemoryAudit(client, "ws-1", undefined, {
+      dryRun: false,
+      deleteBelow: 0,
+    });
+    expect(deletedIds).toHaveLength(0);
+  });
+
   test("stale-draft filter flags draft+0access+age>threshold separately from bucket", async () => {
     const { client } = makeMockClient(
       [

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);
           }
@@ -531,6 +566,9 @@ export class HarmonyApiClient {
       costCents?: number;
       inputTokens?: number;
       outputTokens?: number;
+      cacheCreationInputTokens?: number;
+      cacheReadInputTokens?: number;
+      modelName?: string;
       recentActions?: { action: string; ts: string }[];
     },
   ): Promise<{ session: unknown; created: boolean }> {
@@ -545,6 +583,9 @@ export class HarmonyApiClient {
       costCents?: number;
       inputTokens?: number;
       outputTokens?: number;
+      cacheCreationInputTokens?: number;
+      cacheReadInputTokens?: number;
+      modelName?: string;
     },
   ): Promise<{ session: unknown }> {
     return this.request("DELETE", `/cards/${cardId}/agent-context`, data);

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,9 +271,19 @@ function scoreEntity(
     legacyReasons.push("no graph presence");
   }
 
-  // Bucket
+  // 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 (score < deleteBelow) bucket = "delete";
+  if (boilerplateTitle && deleteBelow > 0) {
+    bucket = "delete";
+    reasons.push("boilerplate title override");
+  } else if (score < deleteBelow) bucket = "delete";
   else if (score < archiveBelow) bucket = "archive";
   else if (score < 70) bucket = "review";
   else bucket = "keep";

package/src/remote.ts

@@ -27,27 +27,58 @@ import { registerHandlers, type ToolDeps } from "./server.js";
 // ---------------------------------------------------------------------------
 const HARMONY_API_URL =
   process.env.HARMONY_API_URL || "https://app.gethmy.com/api";
+const OAUTH_ISSUER = process.env.OAUTH_ISSUER || "https://app.gethmy.com";
+const PUBLIC_MCP_URL = process.env.PUBLIC_MCP_URL || "https://mcp.gethmy.com";
 const PORT = parseInt(process.env.PORT || "3002", 10);
 
 // ---------------------------------------------------------------------------
-// API key validation via Harmony API
+// Token validation via Harmony API
+// Accepts both legacy hmy_* integration keys and hmy_at_* OAuth access tokens.
+// Uses /v1/auth/context — the server decides which table to look in.
 // ---------------------------------------------------------------------------
-interface ApiKeyInfo {
+interface TokenInfo {
+  userId: string;
   workspaceId: string | null;
+  source: "api_key" | "oauth";
 }
 
-async function validateApiKey(apiKey: string): Promise<ApiKeyInfo | null> {
+async function validateToken(token: string): Promise<TokenInfo | null> {
   try {
-    const response = await fetch(`${HARMONY_API_URL}/v1/workspaces`, {
-      headers: { "X-API-Key": apiKey },
+    const response = await fetch(`${HARMONY_API_URL}/v1/auth/context`, {
+      headers: { "X-API-Key": token },
     });
     if (!response.ok) return null;
 
+    const data = (await response.json()) as {
+      userId: string;
+      source: "api_key" | "oauth" | "jwt";
+      workspaceId: string | null;
+    };
+    if (data.source === "jwt") return null; // JWT not allowed on MCP endpoint
+    return {
+      userId: data.userId,
+      workspaceId: data.workspaceId,
+      source: data.source,
+    };
+  } catch {
+    return null;
+  }
+}
+
+// For legacy api_keys: fall back to workspaces list to pick the first one.
+// OAuth tokens already have workspaceId bound at grant time.
+async function resolveWorkspaceForLegacyKey(
+  token: string,
+): Promise<string | null> {
+  try {
+    const response = await fetch(`${HARMONY_API_URL}/v1/workspaces`, {
+      headers: { "X-API-Key": token },
+    });
+    if (!response.ok) return null;
     const data = (await response.json()) as {
       workspaces?: Array<{ id: string }>;
     };
-    const firstWorkspace = data.workspaces?.[0];
-    return { workspaceId: firstWorkspace?.id ?? null };
+    return data.workspaces?.[0]?.id ?? null;
   } catch {
     return null;
   }
@@ -59,10 +90,16 @@ async function validateApiKey(apiKey: string): Promise<ApiKeyInfo | null> {
 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>();
@@ -82,7 +119,7 @@ setInterval(
   30 * 60 * 1000,
 );
 
-function createSession(apiKey: string, keyInfo: ApiKeyInfo): McpSession {
+function createSession(apiKey: string, keyInfo: TokenInfo): McpSession {
   const transport = new WebStandardStreamableHTTPServerTransport({
     sessionIdGenerator: () => crypto.randomUUID(),
     enableJsonResponse: true,
@@ -93,18 +130,38 @@ function createSession(apiKey: string, keyInfo: ApiKeyInfo): 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,
@@ -164,14 +221,57 @@ app.get("/health", (c) =>
   }),
 );
 
-// MCP endpoint - handles POST (JSON-RPC), GET (SSE), DELETE (session close)
-app.all("/mcp", async (c) => {
+// OAuth 2.1 Protected Resource Metadata (RFC 9728 / MCP 2025-11-25).
+// Tells unauthenticated clients which authorization server to use.
+app.get("/.well-known/oauth-protected-resource", (c) =>
+  c.json({
+    resource: PUBLIC_MCP_URL,
+    authorization_servers: [OAUTH_ISSUER],
+    bearer_methods_supported: ["header"],
+    resource_documentation: `${OAUTH_ISSUER}/docs/mcp`,
+  }),
+);
+
+// Unauthenticated 401 that advertises the OAuth metadata discovery point.
+// Claude's `mcp add --transport http` uses this to kick off the flow.
+function unauthenticatedResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      error: "unauthorized",
+      error_description: "Missing or invalid access token",
+    }),
+    {
+      status: 401,
+      headers: {
+        "Content-Type": "application/json",
+        "WWW-Authenticate": `Bearer realm="mcp", resource_metadata="${PUBLIC_MCP_URL}/.well-known/oauth-protected-resource"`,
+      },
+    },
+  );
+}
+
+// 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.
+const handleMcpRequest = async (c: import("hono").Context) => {
   const method = c.req.method;
 
-  // Extract API key from Authorization header
+  // Extract bearer token. Accept OAuth access tokens (hmy_at_) and legacy
+  // integration keys (hmy_). No token → 401 with WWW-Authenticate so Claude
+  // can discover our authorization server.
   const authHeader = c.req.header("Authorization");
   if (!authHeader?.startsWith("Bearer ")) {
-    return c.json({ error: "Missing Authorization: Bearer <api-key>" }, 401);
+    return unauthenticatedResponse();
   }
   const apiKey = authHeader.slice(7);
 
@@ -179,17 +279,44 @@ app.all("/mcp", async (c) => {
   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") {
-    // Could be a new session (initialize) or an existing session we don't know about
-    // Validate API key
-    const keyInfo = await validateApiKey(apiKey);
+    // Validate the token. OAuth tokens carry workspaceId; legacy keys don't,
+    // so we look up workspaces in a follow-up call for those.
+    const keyInfo = await validateToken(apiKey);
     if (!keyInfo) {
-      return c.json({ error: "Invalid API key" }, 401);
+      return unauthenticatedResponse();
+    }
+    if (keyInfo.source === "api_key" && !keyInfo.workspaceId) {
+      keyInfo.workspaceId = await resolveWorkspaceForLegacyKey(apiKey);
     }
 
     // Create new session
@@ -205,13 +332,25 @@ app.all("/mcp", async (c) => {
       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
   return c.json({ error: "Invalid or missing session" }, 404);
-});
+};
+
+app.all("/mcp", handleMcpRequest);
+app.all("/", handleMcpRequest);
 
 // ---------------------------------------------------------------------------
 // Start server