@gethmy/mcp 2.9.3 → 2.9.5

package/dist/lib/config.js

@@ -18,8 +18,6 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-var DEFAULT_API_URL = "https://app.gethmy.com/api";
-var LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
 function getConfigDir() {
   return join(homedir(), ".harmony-mcp");
 }
@@ -29,17 +27,24 @@ function getConfigPath() {
 function getLocalConfigPath(cwd) {
   return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
 }
+function emptyConfig() {
+  return {
+    apiKey: null,
+    apiUrl: DEFAULT_API_URL,
+    activeWorkspaceId: null,
+    activeProjectId: null,
+    userEmail: null,
+    memoryDir: null,
+    oauthAccessToken: null,
+    oauthRefreshToken: null,
+    oauthExpiresAt: null,
+    oauthClientId: null
+  };
+}
 function loadConfig() {
   const configPath = getConfigPath();
   if (!existsSync(configPath)) {
-    return {
-      apiKey: null,
-      apiUrl: DEFAULT_API_URL,
-      activeWorkspaceId: null,
-      activeProjectId: null,
-      userEmail: null,
-      memoryDir: null
-    };
+    return emptyConfig();
   }
   try {
     const data = readFileSync(configPath, "utf-8");
@@ -50,17 +55,14 @@ function loadConfig() {
       activeWorkspaceId: config.activeWorkspaceId || null,
       activeProjectId: config.activeProjectId || null,
       userEmail: config.userEmail || null,
-      memoryDir: config.memoryDir || null
+      memoryDir: config.memoryDir || null,
+      oauthAccessToken: config.oauthAccessToken || null,
+      oauthRefreshToken: config.oauthRefreshToken || null,
+      oauthExpiresAt: typeof config.oauthExpiresAt === "number" ? config.oauthExpiresAt : null,
+      oauthClientId: config.oauthClientId || null
     };
   } catch {
-    return {
-      apiKey: null,
-      apiUrl: DEFAULT_API_URL,
-      activeWorkspaceId: null,
-      activeProjectId: null,
-      userEmail: null,
-      memoryDir: null
-    };
+    return emptyConfig();
   }
 }
 function saveConfig(config) {
@@ -108,13 +110,17 @@ function saveLocalConfig(config, cwd) {
 function hasLocalConfig(cwd) {
   return existsSync(getLocalConfigPath(cwd));
 }
-function getApiKey() {
+function getActiveCredential() {
   const config = loadConfig();
-  if (!config.apiKey) {
-    throw new Error(`Not configured. Run "npx @gethmy/mcp setup" to set your API key.
-` + "You can generate an API key at https://gethmy.com → Settings → API Keys.");
-  }
-  return config.apiKey;
+  if (config.oauthAccessToken)
+    return config.oauthAccessToken;
+  if (config.apiKey)
+    return config.apiKey;
+  throw new Error(`Not configured. Run "npx @gethmy/mcp setup" to connect Harmony.
+` + "Setup authorizes in your browser — no API key handling required.");
+}
+function getApiKey() {
+  return getActiveCredential();
 }
 function getApiUrl() {
   const config = loadConfig();
@@ -157,7 +163,7 @@ function getActiveProjectId(cwd) {
 }
 function isConfigured() {
   const config = loadConfig();
-  return !!config.apiKey;
+  return !!(config.apiKey || config.oauthAccessToken);
 }
 function areSkillsInstalled(cwd) {
   const home = homedir();
@@ -201,6 +207,10 @@ function getMemoryDir() {
     return config.memoryDir;
   return join(homedir(), ".harmony", "memory");
 }
+var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
+var init_config = () => {};
+init_config();
+
 export {
   setUserEmail,
   setActiveWorkspace,
@@ -221,5 +231,6 @@ export {
   getApiKey,
   getActiveWorkspaceId,
   getActiveProjectId,
+  getActiveCredential,
   areSkillsInstalled
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.9.3",
+  "version": "2.9.5",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"
@@ -63,7 +63,7 @@
     "test:unit": "bun test src/__tests__/active-learning.test.ts src/__tests__/context-assembly.test.ts src/__tests__/prompt-builder.test.ts src/__tests__/memory-audit.test.ts src/__tests__/skills.test.ts src/__tests__/hmy-config.test.ts src/__tests__/tool-dispatch.test.ts src/__tests__/mcp-integration.test.ts",
     "test:integration": "bun test src/__tests__/integration-memory-system.test.ts src/__tests__/integration-memory-crud.test.ts",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "bun run build"
+    "prepublishOnly": "bun run typecheck && bun run build"
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",

package/src/api-client.ts

@@ -155,15 +155,21 @@ export class HarmonyApiClient {
   private apiKey: string;
   private apiUrl: string;
   private onUnauthorized?: () => void;
+  private refreshCredential?: () => Promise<string | null>;
 
   constructor(options?: {
     apiKey?: string;
     apiUrl?: string;
     onUnauthorized?: () => void;
+    // Called once on a 401 to obtain a fresh credential (OAuth refresh in stdio
+    // mode). Returns the new credential to retry with, or null to give up and
+    // surface HarmonyUnauthorizedError.
+    refreshCredential?: () => Promise<string | null>;
   }) {
     this.apiKey = options?.apiKey ?? getApiKey();
     this.apiUrl = options?.apiUrl ?? getApiUrl();
     this.onUnauthorized = options?.onUnauthorized;
+    this.refreshCredential = options?.refreshCredential;
   }
 
   getApiUrl(): string {
@@ -217,6 +223,7 @@ export class HarmonyApiClient {
   ): Promise<T> {
     const url = `${this.apiUrl}/v1${path}`;
     let lastError: Error | null = null;
+    let refreshed = false;
     const contentType = options?.contentType || "application/json";
     const accept = options?.accept || "application/json";
 
@@ -253,10 +260,26 @@ 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.
+          // 401: credential rejected. In stdio mode we own an OAuth token, so
+          // try a one-shot refresh and retry with the new credential. If there
+          // is no refresher (remote mode) or it fails, surface a typed error so
+          // the transport layer can issue an HTTP 401 challenge / re-auth.
           if (response.status === 401) {
+            if (this.refreshCredential && !refreshed) {
+              refreshed = true;
+              const fresh = await this.refreshCredential();
+              if (fresh) {
+                this.apiKey = fresh;
+                // A credential refresh is a one-shot, not a network retry, so
+                // give back the attempt slot: a 401 on the final iteration
+                // (after transient errors burned the budget) must still
+                // re-issue with the fresh token rather than throw the stale
+                // error. The `refreshed` guard caps this at one extra pass — a
+                // second 401 falls through to the unauthorized throw.
+                attempt--;
+                continue;
+              }
+            }
             this.onUnauthorized?.();
             throw new HarmonyUnauthorizedError(errorMsg);
           }
@@ -298,6 +321,7 @@ export class HarmonyApiClient {
   ): Promise<string> {
     const url = `${this.apiUrl}/v1${path}`;
     let lastError: Error | null = null;
+    let refreshed = false;
     const contentType = options?.contentType || "application/json";
     const accept = options?.accept || "text/markdown";
 
@@ -323,6 +347,21 @@ export class HarmonyApiClient {
             errorMsg = text || `API error: ${response.status}`;
           }
           if (response.status === 401) {
+            if (this.refreshCredential && !refreshed) {
+              refreshed = true;
+              const fresh = await this.refreshCredential();
+              if (fresh) {
+                this.apiKey = fresh;
+                // A credential refresh is a one-shot, not a network retry, so
+                // give back the attempt slot: a 401 on the final iteration
+                // (after transient errors burned the budget) must still
+                // re-issue with the fresh token rather than throw the stale
+                // error. The `refreshed` guard caps this at one extra pass — a
+                // second 401 falls through to the unauthorized throw.
+                attempt--;
+                continue;
+              }
+            }
             this.onUnauthorized?.();
             throw new HarmonyUnauthorizedError(errorMsg);
           }
@@ -735,6 +774,7 @@ export class HarmonyApiClient {
       cacheCreationInputTokens?: number;
       cacheReadInputTokens?: number;
       modelName?: string;
+      numTurns?: number;
       recentActions?: { action: string; ts: string }[];
       failureReason?:
         | "verification"
@@ -768,6 +808,7 @@ export class HarmonyApiClient {
       cacheCreationInputTokens?: number;
       cacheReadInputTokens?: number;
       modelName?: string;
+      numTurns?: number;
       failureReason?:
         | "verification"
         | "review"
@@ -1660,7 +1701,14 @@ let client: HarmonyApiClient | null = null;
 
 export function getClient(): HarmonyApiClient {
   if (!client) {
-    client = new HarmonyApiClient();
+    // stdio mode owns its OAuth token, so wire the refresh-on-401 path. Lazy
+    // import avoids a module cycle (oauth-refresh → config, api-client → config).
+    client = new HarmonyApiClient({
+      refreshCredential: async () => {
+        const { refreshOAuthToken } = await import("./oauth-refresh.js");
+        return refreshOAuthToken();
+      },
+    });
   }
   return client;
 }

package/src/cli.ts

@@ -59,7 +59,11 @@ program
       console.log("Status: Configured\n");
 
       console.log("API:");
-      console.log(`  Key: ${globalConfig.apiKey?.slice(0, 8)}...`);
+      if (globalConfig.oauthAccessToken) {
+        console.log("  Credential: Browser sign-in (OAuth, workspace-scoped)");
+      } else {
+        console.log(`  Key: ${globalConfig.apiKey?.slice(0, 8)}...`);
+      }
       console.log(`  URL: ${globalConfig.apiUrl}`);
       console.log(
         `  Email: ${globalConfig.userEmail ? maskEmail(globalConfig.userEmail) : "(not set)"}`,
@@ -131,6 +135,10 @@ program
       activeWorkspaceId: null,
       activeProjectId: null,
       userEmail: null,
+      oauthAccessToken: null,
+      oauthRefreshToken: null,
+      oauthExpiresAt: null,
+      oauthClientId: null,
     });
     console.log("Configuration reset successfully");
     console.log("\nTo reconfigure, run: npx @gethmy/mcp setup");
@@ -144,7 +152,10 @@ program
     "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)",
   )
   .option("-f, --force", "Overwrite existing configuration files")
-  .option("-k, --api-key <key>", "API key (skips prompt)")
+  .option(
+    "-k, --api-key <key>",
+    "DEPRECATED (insecure: key leaks via argv/shell history). For unattended CI only — interactive setup uses browser sign-in.",
+  )
   .option("-e, --email <email>", "Your email for auto-assignment")
   .option(
     "-a, --agents <agents...>",

package/src/config.ts

@@ -9,6 +9,16 @@ export interface HarmonyConfig {
   activeProjectId: string | null;
   userEmail: string | null;
   memoryDir: string | null;
+  // OAuth 2.1 credentials (card #364). Preferred over `apiKey` when present —
+  // workspace-scoped + expiring, refreshed via the rotating refresh token.
+  // Acquired by the loopback+PKCE browser flow in `setup` (see oauth-login.ts);
+  // `apiKey` stays as the legacy/CI credential.
+  oauthAccessToken: string | null;
+  oauthRefreshToken: string | null;
+  // Epoch milliseconds at which the access token expires.
+  oauthExpiresAt: number | null;
+  // The public client_id the tokens were issued to — required to refresh them.
+  oauthClientId: string | null;
 }
 
 /**
@@ -35,18 +45,26 @@ export function getLocalConfigPath(cwd?: string): string {
   return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
 }
 
+function emptyConfig(): HarmonyConfig {
+  return {
+    apiKey: null,
+    apiUrl: DEFAULT_API_URL,
+    activeWorkspaceId: null,
+    activeProjectId: null,
+    userEmail: null,
+    memoryDir: null,
+    oauthAccessToken: null,
+    oauthRefreshToken: null,
+    oauthExpiresAt: null,
+    oauthClientId: null,
+  };
+}
+
 export function loadConfig(): HarmonyConfig {
   const configPath = getConfigPath();
 
   if (!existsSync(configPath)) {
-    return {
-      apiKey: null,
-      apiUrl: DEFAULT_API_URL,
-      activeWorkspaceId: null,
-      activeProjectId: null,
-      userEmail: null,
-      memoryDir: null,
-    };
+    return emptyConfig();
   }
 
   try {
@@ -59,16 +77,16 @@ export function loadConfig(): HarmonyConfig {
       activeProjectId: config.activeProjectId || null,
       userEmail: config.userEmail || null,
       memoryDir: config.memoryDir || null,
+      oauthAccessToken: config.oauthAccessToken || null,
+      oauthRefreshToken: config.oauthRefreshToken || null,
+      oauthExpiresAt:
+        typeof config.oauthExpiresAt === "number"
+          ? config.oauthExpiresAt
+          : null,
+      oauthClientId: config.oauthClientId || null,
     };
   } catch {
-    return {
-      apiKey: null,
-      apiUrl: DEFAULT_API_URL,
-      activeWorkspaceId: null,
-      activeProjectId: null,
-      userEmail: null,
-      memoryDir: null,
-    };
+    return emptyConfig();
   }
 }
 
@@ -131,15 +149,25 @@ export function hasLocalConfig(cwd?: string): boolean {
   return existsSync(getLocalConfigPath(cwd));
 }
 
-export function getApiKey(): string {
+/**
+ * The credential the runtime should send as `X-API-Key`. harmony-api accepts
+ * both an OAuth access token (`hmy_at_`) and a legacy key (`hmy_`) on that
+ * header, so callers don't branch. Prefers a fresh OAuth access token, then a
+ * (possibly stale) OAuth access token the caller can refresh on 401, then the
+ * legacy `apiKey`.
+ */
+export function getActiveCredential(): string {
   const config = loadConfig();
-  if (!config.apiKey) {
-    throw new Error(
-      'Not configured. Run "npx @gethmy/mcp setup" to set your API key.\n' +
-        "You can generate an API key at https://gethmy.com → Settings → API Keys.",
-    );
-  }
-  return config.apiKey;
+  if (config.oauthAccessToken) return config.oauthAccessToken;
+  if (config.apiKey) return config.apiKey;
+  throw new Error(
+    'Not configured. Run "npx @gethmy/mcp setup" to connect Harmony.\n' +
+      "Setup authorizes in your browser — no API key handling required.",
+  );
+}
+
+export function getApiKey(): string {
+  return getActiveCredential();
 }
 
 export function getApiUrl(): string {
@@ -203,7 +231,7 @@ export function getActiveProjectId(cwd?: string): string | null {
 
 export function isConfigured(): boolean {
   const config = loadConfig();
-  return !!config.apiKey;
+  return !!(config.apiKey || config.oauthAccessToken);
 }
 
 /**

package/src/graph-expansion.ts

@@ -36,8 +36,9 @@ export async function autoExpandGraph(
       limit: 20,
     });
 
-    candidates = (entities as Array<{ id: string }>)
-      .filter((e) => e.id !== entityId)
+    // Filter: exclude self, only high-enough confidence results
+    candidates = (entities as Array<{ id: string; confidence?: number }>)
+      .filter((e) => e.id !== entityId && (e.confidence ?? 1) >= 0.4)
       .slice(0, maxRelations);
 
     // Retry once after 2s if no candidates found (handles embedding generation race)
@@ -47,8 +48,10 @@ export async function autoExpandGraph(
         project_id: projectId,
         limit: 20,
       });
-      candidates = (retry.entities as Array<{ id: string }>)
-        .filter((e) => e.id !== entityId)
+      candidates = (
+        retry.entities as Array<{ id: string; confidence?: number }>
+      )
+        .filter((e) => e.id !== entityId && (e.confidence ?? 1) >= 0.4)
         .slice(0, maxRelations);
     }
 

package/src/http.ts

@@ -11,7 +11,7 @@
  */
 
 import { serve } from "bun";
-import { Hono } from "hono";
+import { type Context, Hono } from "hono";
 import { cors } from "hono/cors";
 import { loadConfig } from "./config.js";
 
@@ -122,18 +122,7 @@ app.get("/", (c) =>
 );
 
 // Generic proxy handler
-async function handleRequest(
-  c: {
-    req: {
-      method: string;
-      url: string;
-      header: (name: string) => string | undefined;
-    };
-    json: () => Promise<unknown>;
-  },
-  method: string,
-  path: string,
-) {
+async function handleRequest(c: Context, method: string, path: string) {
   try {
     const authHeader = c.req.header("Authorization");
     const apiKey = c.req.header("X-API-Key");
@@ -141,7 +130,7 @@ async function handleRequest(
     let body: unknown;
     if (["POST", "PATCH", "PUT"].includes(method)) {
       try {
-        body = await c.json();
+        body = await c.req.json();
       } catch {
         // No body or invalid JSON
       }

package/src/memory-floor.ts

@@ -55,6 +55,7 @@ export type FloorRuleId =
   | "frequency-meta"
   | "self-referential"
   | "bare-type-prefix"
+  | "impl-detail-lesson"
   | "specificity-floor"
   | "length-floor"
   | "operational-data-ban";
@@ -218,7 +219,7 @@ export function validateMemoryQuality(
       rule: "impl-detail-lesson",
       message:
         "Lesson body reads as an implementation TODO/issue, not a learning. Convert to a positive takeaway or move to a code comment.",
-    } as FloorRejection;
+    };
   }
 
   // Rule 4: Specificity floor (skipped for doc-source imports — they may