@gethmy/mcp 2.4.2 → 2.4.4

package/package.json

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

@@ -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(
@@ -504,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 }> {
@@ -518,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

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[] = [];