@gethmy/mcp 2.4.3 → 2.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.4.3",
+  "version": "2.4.4",
   "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,66 @@ 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 override");
+  });
+
+  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

@@ -531,6 +531,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 +548,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

@@ -253,9 +253,17 @@ function scoreEntity(
     legacyReasons.push("no graph presence");
   }
 
-  // Bucket
+  // 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.
   let bucket: AuditBucket;
-  if (score < deleteBelow) bucket = "delete";
+  if (boilerplate && deleteBelow > 0) {
+    bucket = "delete";
+    reasons.push("boilerplate 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;
   }
@@ -82,7 +113,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,
@@ -164,14 +195,47 @@ 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"`,
+      },
+    },
+  );
+}
+
+// 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);
 
@@ -185,11 +249,14 @@ app.all("/mcp", async (c) => {
   }
 
   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
@@ -211,7 +278,10 @@ app.all("/mcp", async (c) => {
 
   // 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