@gethmy/mcp 2.5.5 → 2.5.7

package/README.md

@@ -6,7 +6,7 @@ Enables AI coding agents (Claude Code, OpenAI Codex, Cursor) to interact with yo
 ## Features
 
 - **56 MCP Tools** for full board control, knowledge graph, and workflow plans
-- **4 Global Skills** — `/hmy`, `/hmy-plan`, `/hmy-cleanup`, `/hmy-standup`, served from the DB-backed [skill hub](../../docs/skills.md) with auto-update and admin-managed versioning
+- **5 Global Skills** — `/hmy`, `/hmy-plan`, `/hmy-cleanup`, `/hmy-standup`, `/hmy-memory-prune`, served from the DB-backed [skill hub](../../docs/skills.md) with auto-update and admin-managed versioning
 - **Knowledge Graph Memory** — Phase 1 surface: hybrid retrieval (vector + lexical + RRF), session-scoped working memory, activity feed. See [docs/memory.md](../../docs/memory.md)
 - **GSD Workflow Plans** - plan/execute/verify/done lifecycle with auto card creation
 - **Card Linking** - create relationships between cards (blocks, relates_to, duplicates, is_part_of)
@@ -154,7 +154,7 @@ npx @gethmy/mcp serve              # Start MCP server
 
 ## Skills
 
-Four global skills ship with the MCP server and are installed automatically by `npx @gethmy/mcp setup`. They live in the `skill_resource` Postgres table, are fetched via `GET /v1/skills/<name>`, and render-time composed with a shared auto-update preamble.
+Five global skills ship with the MCP server and are installed automatically by `npx @gethmy/mcp setup`. They live in the `skill_resource` Postgres table, are fetched via `GET /v1/skills/<name>`, and render-time composed with a shared auto-update preamble.
 
 For the full skill hub architecture (storage, versioning, auto-update, admin management), see [docs/skills.md](../../docs/skills.md).
 

package/dist/cli.js

@@ -4957,6 +4957,7 @@ async function refreshSkills() {
 }
 
 // src/tui/setup.ts
+import { createHash as createHash3 } from "node:crypto";
 import {
   existsSync as existsSync7,
   lstatSync,
@@ -5028,7 +5029,7 @@ import { isAbsolute, join as join4, resolve, sep as sep2 } from "node:path";
 import * as p from "@clack/prompts";
 
 // src/tui/theme.ts
-import * as pc from "picocolors";
+import pc from "picocolors";
 var symbols = {
   harmony: "▲",
   check: "✓",
@@ -5729,7 +5730,13 @@ async function runDocsStep(cwd) {
 }
 
 // src/tui/writer.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "node:fs";
+import {
+  chmodSync,
+  existsSync as existsSync6,
+  mkdirSync as mkdirSync4,
+  readFileSync as readFileSync5,
+  writeFileSync as writeFileSync4
+} from "node:fs";
 import { homedir as homedir3 } from "node:os";
 import { dirname as dirname2 } from "node:path";
 import * as p2 from "@clack/prompts";
@@ -5745,8 +5752,12 @@ function writeFile(filePath, content, options = {}) {
   }
   try {
     ensureDir(dirname2(filePath));
-    const mode = filePath.includes(".harmony-mcp") ? 384 : 420;
+    const defaultMode = filePath.includes(".harmony-mcp") ? 384 : 420;
+    const mode = options.mode ?? defaultMode;
     writeFileSync4(filePath, content, { mode });
+    if (options.mode !== undefined) {
+      chmodSync(filePath, options.mode);
+    }
     return { path: filePath, action: exists ? "update" : "create" };
   } catch (error) {
     return {
@@ -5857,7 +5868,10 @@ async function writeFilesWithProgress(files, options = {}) {
     } else if (file.type === "toml" && file.tomlSection) {
       result = appendToToml(file.path, file.tomlSection, file.content, options);
     } else {
-      result = writeFile(file.path, file.content, options);
+      result = writeFile(file.path, file.content, {
+        ...options,
+        mode: file.mode
+      });
     }
     results.push(result);
     await new Promise((resolve2) => setTimeout(resolve2, 50));
@@ -5993,6 +6007,22 @@ async function fetchProjects(apiKey, workspaceId) {
   const data = await response.json();
   return data.projects || [];
 }
+async function resolveProjectSlug(apiKey, slug) {
+  const response = await fetch(`${API_URL}/v1/projects/resolve/${encodeURIComponent(slug)}`, {
+    method: "GET",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": apiKey
+    }
+  });
+  if (response.status === 404)
+    return null;
+  if (!response.ok) {
+    throw new Error(`Failed to resolve project slug: ${response.status}`);
+  }
+  const data = await response.json();
+  return { workspaceId: data.workspaceId, projectId: data.projectId };
+}
 async function getAgentFiles(agentId, cwd, installMode = "global") {
   const home = homedir4();
   const files = [];
@@ -6035,6 +6065,24 @@ async function getAgentFiles(agentId, cwd, installMode = "global") {
         throw new Error(`Failed to fetch ${skillFailures.length}/${installableNames.length} skill(s) from /v1/skills:
 ${summary}`);
       }
+      try {
+        const updateCheckFetched = await client3.fetchSkill("hmy-update-check");
+        const actualHash = createHash3("sha256").update(updateCheckFetched.content).digest("hex");
+        if (actualHash !== updateCheckFetched.sha256) {
+          throw new Error(`hmy-update-check integrity check failed: expected ${updateCheckFetched.sha256}, got ${actualHash}`);
+        }
+        files.push({
+          path: join5(home, ".hmy", "bin", "hmy-update-check"),
+          content: updateCheckFetched.content,
+          type: "text",
+          mode: 493
+        });
+        files.push({
+          path: join5(home, ".hmy", "VERSION"),
+          content: versionInfo.version,
+          type: "text"
+        });
+      } catch {}
       break;
     }
     case "codex": {
@@ -6227,7 +6275,7 @@ async function runSetup(options = {}) {
   let needsApiKey = !alreadyConfigured;
   let needsSkills = !skillsStatus.installed || options.force;
   let needsContext = !hasContext && !options.skipContext;
-  if (options.workspaceId || options.projectId) {
+  if (options.workspaceId || options.projectId || options.projectSlug) {
     needsContext = true;
   }
   let apiKey = options.apiKey || existingConfig.apiKey;
@@ -6449,6 +6497,21 @@ async function runSetup(options = {}) {
   let selectedProjectId = selectedProjectIdFromSignup || options.projectId;
   let selectedWorkspaceName = selectedWorkspaceNameFromSignup;
   let selectedProjectName = selectedProjectNameFromSignup;
+  if (options.projectSlug && apiKey && (!selectedWorkspaceId || !selectedProjectId)) {
+    spinner3.start(`Resolving project slug "${options.projectSlug}"...`);
+    try {
+      const resolved = await resolveProjectSlug(apiKey, options.projectSlug);
+      if (resolved) {
+        selectedWorkspaceId = selectedWorkspaceId || resolved.workspaceId;
+        selectedProjectId = selectedProjectId || resolved.projectId;
+        spinner3.stop(colors.success(`Resolved "${options.projectSlug}"`));
+      } else {
+        spinner3.stop(colors.warning(`No project found for slug "${options.projectSlug}"`));
+      }
+    } catch (error) {
+      spinner3.stop(colors.warning(`Could not resolve slug: ${error instanceof Error ? error.message : "unknown error"}`));
+    }
+  }
   if (createdNewAccount) {
     needsContext = false;
   }
@@ -6775,13 +6838,14 @@ program.command("reset").description("Remove stored configuration").action(() =>
   console.log(`
 To reconfigure, run: npx @gethmy/mcp setup`);
 });
-program.command("setup").description("Smart setup wizard for Harmony MCP (recommended)").option("-f, --force", "Overwrite existing configuration files").option("-k, --api-key <key>", "API key (skips prompt)").option("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context").option("-p, --project <id>", "Set project context").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").action(async (options) => {
+program.command("setup").description("Smart setup wizard for Harmony MCP (recommended)").argument("[slug]", "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("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context (UUID)").option("-p, --project <id>", "Set project context (UUID)").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").action(async (slug, options) => {
   await runSetup({
     force: options.force,
     apiKey: options.apiKey,
     userEmail: options.email,
     agents: options.agents,
     installMode: options.global ? "global" : options.local ? "local" : undefined,
+    projectSlug: slug,
     workspaceId: options.workspace,
     projectId: options.project,
     skipContext: options.skipContext,

package/package.json

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

package/src/cli.ts

@@ -139,6 +139,10 @@ program
 program
   .command("setup")
   .description("Smart setup wizard for Harmony MCP (recommended)")
+  .argument(
+    "[slug]",
+    "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("-e, --email <email>", "Your email for auto-assignment")
@@ -148,13 +152,13 @@ program
   )
   .option("-l, --local", "Install skills locally in project directory")
   .option("-g, --global", "Install skills globally (recommended)")
-  .option("-w, --workspace <id>", "Set workspace context")
-  .option("-p, --project <id>", "Set project context")
+  .option("-w, --workspace <id>", "Set workspace context (UUID)")
+  .option("-p, --project <id>", "Set project context (UUID)")
   .option("--skip-context", "Skip workspace/project selection")
   .option("--skip-docs", "Skip project docs scaffold/verification")
   .option("--new", "Create a new account (skip the choice prompt)")
   .option("-n, --name <name>", "Full name (for account creation)")
-  .action(async (options) => {
+  .action(async (slug, options) => {
     await runSetup({
       force: options.force,
       apiKey: options.apiKey,
@@ -165,6 +169,7 @@ program
         : options.local
           ? "local"
           : undefined,
+      projectSlug: slug,
       workspaceId: options.workspace,
       projectId: options.project,
       skipContext: options.skipContext,

package/src/tui/setup.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import {
   existsSync,
   lstatSync,
@@ -38,6 +39,7 @@ export interface SetupOptions {
   installMode?: InstallMode;
   workspaceId?: string;
   projectId?: string;
+  projectSlug?: string;
   skipContext?: boolean;
   skipDocs?: boolean;
   newAccount?: boolean;
@@ -211,11 +213,40 @@ async function fetchProjects(
   return data.projects || [];
 }
 
+/**
+ * Resolve a project slug to {workspaceId, projectId}. Used by
+ * `npx @gethmy/mcp setup <slug>` so users don't have to copy raw UUIDs.
+ */
+async function resolveProjectSlug(
+  apiKey: string,
+  slug: string,
+): Promise<{ workspaceId: string; projectId: string } | null> {
+  const response = await fetch(
+    `${API_URL}/v1/projects/resolve/${encodeURIComponent(slug)}`,
+    {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": apiKey,
+      },
+    },
+  );
+
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    throw new Error(`Failed to resolve project slug: ${response.status}`);
+  }
+
+  const data = await response.json();
+  return { workspaceId: data.workspaceId, projectId: data.projectId };
+}
+
 export interface FileToWrite {
   path: string;
   content: string;
   type: "text" | "json" | "toml";
   tomlSection?: string;
+  mode?: number;
 }
 
 export interface SymlinkToCreate {
@@ -288,6 +319,36 @@ async function getAgentFiles(
         );
       }
 
+      // Pre-populate ~/.hmy/VERSION and ~/.hmy/bin/hmy-update-check so the
+      // lazy bootstrap inside the skill preamble is bypassed on first run.
+      // Without this, the bootstrap writes "1.0.0" as a fallback whenever the
+      // version fetch times out (edge function cold start) — triggering a
+      // spurious "upgrade to v6" prompt the moment the skill is first invoked.
+      try {
+        const updateCheckFetched = await client.fetchSkill("hmy-update-check");
+        const actualHash = createHash("sha256")
+          .update(updateCheckFetched.content)
+          .digest("hex");
+        if (actualHash !== updateCheckFetched.sha256) {
+          throw new Error(
+            `hmy-update-check integrity check failed: expected ${updateCheckFetched.sha256}, got ${actualHash}`,
+          );
+        }
+        files.push({
+          path: join(home, ".hmy", "bin", "hmy-update-check"),
+          content: updateCheckFetched.content,
+          type: "text",
+          mode: 0o755,
+        });
+        files.push({
+          path: join(home, ".hmy", "VERSION"),
+          content: versionInfo.version,
+          type: "text",
+        });
+      } catch {
+        // Non-fatal — bootstrap will install both on first skill invocation.
+      }
+
       // Note: MCP server registration is handled separately via `claude mcp add` CLI
       // in runSetup() after file writing, with fallback to settings.json if CLI unavailable
       break;
@@ -524,8 +585,8 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   let needsSkills = !skillsStatus.installed || options.force;
   let needsContext = !hasContext && !options.skipContext;
 
-  // If workspace/project provided via flags, we'll set context
-  if (options.workspaceId || options.projectId) {
+  // If workspace/project/slug provided via flags or argument, we'll set context
+  if (options.workspaceId || options.projectId || options.projectSlug) {
     needsContext = true;
   }
 
@@ -806,6 +867,35 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
     selectedWorkspaceNameFromSignup;
   let selectedProjectName: string | undefined = selectedProjectNameFromSignup;
 
+  // Resolve project slug shorthand (e.g. `npx @gethmy/mcp setup harmony-6590761b`).
+  // Slug wins over --workspace/--project flags only when those aren't already set
+  // from signup or explicit flags.
+  if (
+    options.projectSlug &&
+    apiKey &&
+    (!selectedWorkspaceId || !selectedProjectId)
+  ) {
+    spinner.start(`Resolving project slug "${options.projectSlug}"...`);
+    try {
+      const resolved = await resolveProjectSlug(apiKey, options.projectSlug);
+      if (resolved) {
+        selectedWorkspaceId = selectedWorkspaceId || resolved.workspaceId;
+        selectedProjectId = selectedProjectId || resolved.projectId;
+        spinner.stop(colors.success(`Resolved "${options.projectSlug}"`));
+      } else {
+        spinner.stop(
+          colors.warning(`No project found for slug "${options.projectSlug}"`),
+        );
+      }
+    } catch (error) {
+      spinner.stop(
+        colors.warning(
+          `Could not resolve slug: ${error instanceof Error ? error.message : "unknown error"}`,
+        ),
+      );
+    }
+  }
+
   // Skip context selection if we just created a new account
   if (createdNewAccount) {
     needsContext = false;

package/src/tui/theme.ts

@@ -1,4 +1,4 @@
-import * as pc from "picocolors";
+import pc from "picocolors";
 
 /**
  * Consistent theme for Harmony MCP TUI

package/src/tui/writer.ts

@@ -1,4 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname } from "node:path";
 import * as p from "@clack/prompts";
@@ -15,6 +21,7 @@ export interface FileResult {
 interface WriteOptions {
   force?: boolean;
   merge?: boolean;
+  mode?: number;
 }
 
 /**
@@ -42,9 +49,12 @@ export function writeFile(
 
   try {
     ensureDir(dirname(filePath));
-    // Use restrictive permissions for config files
-    const mode = filePath.includes(".harmony-mcp") ? 0o600 : 0o644;
+    const defaultMode = filePath.includes(".harmony-mcp") ? 0o600 : 0o644;
+    const mode = options.mode ?? defaultMode;
     writeFileSync(filePath, content, { mode });
+    if (options.mode !== undefined) {
+      chmodSync(filePath, options.mode);
+    }
     return { path: filePath, action: exists ? "update" : "create" };
   } catch (error) {
     return {
@@ -183,6 +193,7 @@ export async function writeFilesWithProgress(
     type: "text" | "json" | "toml";
     jsonKey?: string;
     tomlSection?: string;
+    mode?: number;
   }>,
   options: WriteOptions = {},
 ): Promise<FileResult[]> {
@@ -201,7 +212,10 @@ export async function writeFilesWithProgress(
     } else if (file.type === "toml" && file.tomlSection) {
       result = appendToToml(file.path, file.tomlSection, file.content, options);
     } else {
-      result = writeFile(file.path, file.content, options);
+      result = writeFile(file.path, file.content, {
+        ...options,
+        mode: file.mode,
+      });
     }
 
     results.push(result);