@gethmy/mcp 2.5.2 → 2.5.5

package/README.md

@@ -6,9 +6,8 @@ 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
-- **Knowledge Graph Memory** - persistent memory with entity types, tiers, scopes, and typed relations
-- **Active Learning** - auto-extracts lessons, solutions, and error patterns from completed work sessions
-- **Context Assembly** - token-budget-aware memory injection into AI prompts
+- **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
+- **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)
 - **Prompt Builder** - generate AI-ready prompts from cards with context
@@ -16,7 +15,7 @@ Enables AI coding agents (Claude Code, OpenAI Codex, Cursor) to interact with yo
 - **Auto-Session Detection** - automatically starts/ends sessions when agents interact with cards
 - **Auto-Assignment** - automatically assign cards to you when starting agent sessions
 - **Memory Sync** - bidirectional sync between local markdown files and remote database
-- **Multi-Agent Support** - works with Claude Code, Codex, Cursor
+- **Multi-Agent Support** - works with Claude Code, Codex, Cursor, Claude.ai
 - **Smart Setup** - one command configures everything
 - **API Key Authentication** - no database credentials required
 
@@ -155,6 +154,10 @@ 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.
+
+For the full skill hub architecture (storage, versioning, auto-update, admin management), see [docs/skills.md](../../docs/skills.md).
+
 ### `/hmy` — Card Workflow
 
 When you start working on a card (e.g., `/hmy #42`):
@@ -191,6 +194,18 @@ A single command for both creating and executing plans. It auto-detects intent b
 3. Offers options: create single card, create multiple cards, analyze only, or skip
 4. Creates cards and advances the plan phase
 
+### `/hmy-cleanup` — Board Audit
+
+Scans the board for stale cards — long-idle, missing owners, or stuck in review — and proposes cleanup actions. Read-only by default; opt-in to apply suggestions.
+
+### `/hmy-standup` — Daily Summary
+
+Generates a structured standup summary: what shipped, what's in progress, what's blocked, and where agents need input. Pulls from card activity, plan progress, and the memory activity feed.
+
+### Auto-Update
+
+Every skill ships with an `hmy-update-check` preamble that fires on invocation. It compares local versions against `/v1/skills/version` and prompts (or silently auto-installs, if `~/.hmy/config.yaml` has `auto_upgrade: true`). Snooze levels: 24h / 48h / 7d.
+
 ## Available Tools
 
 ### Card Operations

package/dist/cli.js

@@ -1321,11 +1321,6 @@ class HarmonyApiClient {
   async fetchSkill(name) {
     return this.request("GET", `/skills/${encodeURIComponent(name)}`);
   }
-  async recordSkillInvocation(name) {
-    try {
-      await this.request("POST", "/skills/telemetry", { name });
-    } catch {}
-  }
   async listWorkspaces() {
     return this.request("GET", "/workspaces");
   }
@@ -3667,7 +3662,6 @@ function registerHandlers(server, deps) {
         throw new Error(`Cannot read skill "${name}": Harmony MCP server is not configured. Run \`hmy-mcp setup\`.`);
       }
       const client3 = deps.getClient();
-      client3.recordSkillInvocation(name);
       const fetched = await client3.fetchSkill(name);
       return {
         contents: [
@@ -4786,7 +4780,6 @@ class HarmonyMCPServer {
 // src/skills.ts
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname } from "node:path";
-var VERSION_MARKER_PREFIX = "<!-- skills-version:";
 var HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
 
 Start work on a Harmony card. Card reference: $ARGUMENTS
@@ -4863,17 +4856,34 @@ If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
 **AI:** \`harmony_generate_prompt\`, \`harmony_process_command\`
 `;
 function buildSkillFile(skill) {
-  const major = Number.parseInt(skill.version.split(".")[0] ?? "", 10);
-  if (!Number.isFinite(major) || major < 1) {
-    throw new Error(`Invalid skill version: ${skill.version}`);
+  if (skill.skillVersion !== undefined && !hasMetadataVersion(skill.content)) {
+    return injectMetadataVersion(skill.content, skill.skillVersion);
   }
-  const trimmed = skill.content.replace(/\n+$/, "");
-  return `${trimmed}
-${VERSION_MARKER_PREFIX}${major} -->`;
+  return skill.content;
+}
+function hasMetadataVersion(content) {
+  return parseSkillVersion(content) !== null;
+}
+function injectMetadataVersion(content, version) {
+  const fmMatch = content.match(/^(---\n[\s\S]*?\n)(---\n)([\s\S]*)$/);
+  if (!fmMatch)
+    return content;
+  const [, head, close, body] = fmMatch;
+  const block = `metadata:
+  version: "${version}"
+`;
+  return `${head}${block}${close}${body}`;
 }
 function parseSkillVersion(content) {
-  const match = content.match(/<!-- skills-version:(\d+) -->/);
-  return match ? match[1] : null;
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const fm = fmMatch[1];
+    const verMatch = fm.match(/^metadata:[\s\S]*?\n[ \t]+version:[ \t]*["']?(\d+)["']?\s*$/m);
+    if (verMatch)
+      return verMatch[1];
+  }
+  const legacy = content.match(/<!-- skills-version:(\d+) -->/);
+  return legacy ? legacy[1] : null;
 }
 function findSkillFiles(paths, knownNames) {
   const results = [];
@@ -4919,18 +4929,16 @@ async function refreshSkills() {
     }
     if (skillFiles.length === 0)
       return;
-    const remoteMajor = Number.parseInt(versionInfo.version.split(".")[0] ?? "", 10);
-    if (!Number.isFinite(remoteMajor))
-      return;
     let updated = false;
     for (const { name, filePath } of skillFiles) {
       try {
         const currentContent = readFileSync3(filePath, "utf-8");
         const localVersion = parseSkillVersion(currentContent);
-        if (localVersion !== null && Number(localVersion) >= remoteMajor) {
+        const fetched = await client3.fetchSkill(name);
+        const remoteVersion = fetched.skillVersion;
+        if (remoteVersion !== undefined && localVersion !== null && Number(localVersion) >= remoteVersion) {
           continue;
         }
-        const fetched = await client3.fetchSkill(name);
         const newContent = buildSkillFile(fetched);
         const dir = dirname(filePath);
         if (!existsSync3(dir))
@@ -4943,7 +4951,7 @@ async function refreshSkills() {
       }
     }
     if (updated) {
-      console.error(`Harmony: Updated skills to v${versionInfo.version}`);
+      console.error("Harmony: Refreshed skills from server");
     }
   } catch {}
 }

package/dist/index.js

@@ -1317,11 +1317,6 @@ class HarmonyApiClient {
   async fetchSkill(name) {
     return this.request("GET", `/skills/${encodeURIComponent(name)}`);
   }
-  async recordSkillInvocation(name) {
-    try {
-      await this.request("POST", "/skills/telemetry", { name });
-    } catch {}
-  }
   async listWorkspaces() {
     return this.request("GET", "/workspaces");
   }
@@ -3663,7 +3658,6 @@ function registerHandlers(server, deps) {
         throw new Error(`Cannot read skill "${name}": Harmony MCP server is not configured. Run \`hmy-mcp setup\`.`);
       }
       const client3 = deps.getClient();
-      client3.recordSkillInvocation(name);
       const fetched = await client3.fetchSkill(name);
       return {
         contents: [

package/dist/lib/api-client.js

@@ -924,11 +924,6 @@ class HarmonyApiClient {
   async fetchSkill(name) {
     return this.request("GET", `/skills/${encodeURIComponent(name)}`);
   }
-  async recordSkillInvocation(name) {
-    try {
-      await this.request("POST", "/skills/telemetry", { name });
-    } catch {}
-  }
   async listWorkspaces() {
     return this.request("GET", "/workspaces");
   }

package/package.json

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

package/src/api-client.ts

@@ -342,10 +342,15 @@ export class HarmonyApiClient {
   /**
    * GET /v1/skills/{name} — authenticated content fetch.
    * Returns rendered SKILL.md (frontmatter + body) ready to install.
+   *
+   * Phase 3b: `skillVersion` (per-skill integer) is returned alongside the
+   * legacy aggregate `version` string so refreshSkills can compare per-skill
+   * instead of treating any global bump as "everything stale."
    */
   async fetchSkill(name: string): Promise<{
     name: string;
     version: string;
+    skillVersion?: number;
     content: string;
     sha256: string;
     signature: string;
@@ -353,27 +358,6 @@ export class HarmonyApiClient {
     return this.request("GET", `/skills/${encodeURIComponent(name)}`);
   }
 
-  /**
-   * POST /v1/skills/telemetry — fire-and-forget activation signal.
-   * Called from the ReadResourceRequest handler when an agent reads
-   * a harmony://skills/<name> resource. Increments invocation_count +
-   * sets last_used = now() on the matching skill_resource row.
-   *
-   * Best-effort: returns void; never throws. If the endpoint doesn't
-   * exist yet (pre-Phase-2 backend), or the network is flaky, the
-   * activation is dropped silently. The skill content read itself
-   * is NOT gated on this call succeeding.
-   */
-  async recordSkillInvocation(name: string): Promise<void> {
-    try {
-      await this.request("POST", "/skills/telemetry", { name });
-    } catch {
-      // Fire-and-forget: any failure (404 if endpoint not deployed yet,
-      // 401 if API key rotated, network timeout) is swallowed so the
-      // caller can proceed with serving content.
-    }
-  }
-
   // ============ WORKSPACE OPERATIONS ============
 
   async listWorkspaces(): Promise<{ workspaces: unknown[] }> {

package/src/server.ts

@@ -1533,9 +1533,7 @@ export const RESOURCES = [
 /**
  * Build the dynamic resource list. Skill resources (harmony://skills/<name>)
  * are derived at request time from /v1/skills/version so the list always
- * matches what the agent will get on read. Phase 1 of card #162 — the
- * ReadResourceRequest on harmony://skills/<name> is the activation signal
- * for skill telemetry.
+ * matches what the agent will get on read.
  *
  * Offline / unauthenticated → returns just the static RESOURCES. Agents
  * that can't reach the API still see the context resource and any error
@@ -1716,11 +1714,7 @@ export function registerHandlers(server: Server, deps: ToolDeps): void {
       };
     }
 
-    // harmony://skills/<name> — Phase 1 of card #162. This read IS the
-    // activation event: agent matched the skill's description, harness
-    // calls ReadResource, we fire fire-and-forget telemetry before
-    // returning the body. recordSkillInvocation() swallows all errors
-    // so a telemetry outage never blocks skill delivery.
+    // harmony://skills/<name> — serve the rendered SKILL.md.
     const SKILL_URI_RE = /^harmony:\/\/skills\/([a-z0-9][a-z0-9-]*[a-z0-9])$/;
     const skillMatch = uri.match(SKILL_URI_RE);
     if (skillMatch) {
@@ -1731,10 +1725,6 @@ export function registerHandlers(server: Server, deps: ToolDeps): void {
         );
       }
       const client = deps.getClient();
-      // Fire-and-forget BEFORE awaiting the content fetch so a slow
-      // telemetry endpoint never delays skill delivery. The promise
-      // is intentionally dropped (caught inside recordSkillInvocation).
-      void client.recordSkillInvocation(name);
       const fetched = await client.fetchSkill(name);
       return {
         contents: [

package/src/skills.ts

@@ -3,8 +3,6 @@ import { dirname } from "node:path";
 import { HarmonyApiClient } from "./api-client.js";
 import { areSkillsInstalled, isConfigured } from "./config.js";
 
-const VERSION_MARKER_PREFIX = "<!-- skills-version:";
-
 /**
  * Legacy workflow prompt used by Codex / Cursor agents. Kept inline because
  * those agents install via AGENTS.md and not via /v1/skills. Claude Code
@@ -88,35 +86,76 @@ If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
 
 /**
  * Shape of a /v1/skills/{name} response. Used by buildSkillFile + tests.
+ *
+ * Phase 3b: `skillVersion` is the per-skill integer from `skill_resource.version`.
+ * `version` remains the aggregate "<major>.0.0" string used by the bash bootstrap
+ * for cache freshness — kept for compatibility, not load-bearing for refresh.
  */
 export interface FetchedSkill {
   name: string;
-  version: string; // "X.Y.Z" aggregate from /v1/skills/{name}
-  content: string; // rendered SKILL.md (frontmatter + body), already complete
+  version: string;
+  /** Per-skill row.version (Phase 3b). Optional during rollout — older harmony-api
+   *  deployments may omit it; treat absence as "trust the rendered frontmatter". */
+  skillVersion?: number;
+  content: string;
 }
 
 /**
- * Append the version marker so refreshSkills() can detect stale files later.
- * The harmony-api distribution shape omits the marker; mcp-server adds it on
- * install so parseSkillVersion() can read it back. The marker integer is the
- * major component of the aggregate version (e.g., "5.0.0" → 5).
+ * Pass the API-rendered SKILL.md through to disk. As of Phase 3b the
+ * frontmatter already carries `metadata.version: "<N>"` (rendered server-side
+ * by harmony-api), which is the source of truth `parseSkillVersion` reads on
+ * the next refresh. No EOF marker is appended.
+ *
+ * If `skillVersion` is provided AND the rendered content lacks the metadata.version
+ * block (older harmony-api deployment), we splice it in so install state always
+ * carries a parseable version. This preserves Phase-3b semantics across rolling
+ * deploys where the API hasn't been upgraded yet.
  */
 export function buildSkillFile(skill: FetchedSkill): string {
-  const major = Number.parseInt(skill.version.split(".")[0] ?? "", 10);
-  if (!Number.isFinite(major) || major < 1) {
-    throw new Error(`Invalid skill version: ${skill.version}`);
+  if (skill.skillVersion !== undefined && !hasMetadataVersion(skill.content)) {
+    return injectMetadataVersion(skill.content, skill.skillVersion);
   }
-  const trimmed = skill.content.replace(/\n+$/, "");
-  return `${trimmed}\n${VERSION_MARKER_PREFIX}${major} -->`;
+  return skill.content;
+}
+
+function hasMetadataVersion(content: string): boolean {
+  return parseSkillVersion(content) !== null;
+}
+
+/**
+ * Splice `metadata.version: "<N>"` into the frontmatter of a rendered
+ * SKILL.md. Only used when harmony-api hasn't been upgraded to Phase-3b
+ * yet but mcp-server has — the fallback keeps install state consistent.
+ */
+function injectMetadataVersion(content: string, version: number): string {
+  const fmMatch = content.match(/^(---\n[\s\S]*?\n)(---\n)([\s\S]*)$/);
+  if (!fmMatch) return content;
+  const [, head, close, body] = fmMatch;
+  const block = `metadata:\n  version: "${version}"\n`;
+  return `${head}${block}${close}${body}`;
 }
 
 /**
- * Parse the embedded version marker out of an installed skill file.
- * Returns null if no marker is found — caller treats that as "stale".
+ * Parse `metadata.version` out of an installed skill's frontmatter.
+ * Falls back to the legacy `<!-- skills-version:N -->` EOF marker so files
+ * installed by pre-Phase-3b mcp-server builds keep refreshing correctly
+ * until they're rewritten. Returns null when neither is present — the
+ * caller treats null as "stale, rewrite from API".
  */
 function parseSkillVersion(content: string): string | null {
-  const match = content.match(/<!-- skills-version:(\d+) -->/);
-  return match ? match[1] : null;
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const fm = fmMatch[1];
+    // Match a `version:` line under a `metadata:` block. Tolerates either
+    // 2-space or 4-space child indentation and "..." or '...' quoting.
+    const verMatch = fm.match(
+      /^metadata:[\s\S]*?\n[ \t]+version:[ \t]*["']?(\d+)["']?\s*$/m,
+    );
+    if (verMatch) return verMatch[1];
+  }
+  // Legacy fallback — installed by pre-Phase-3b mcp-server builds.
+  const legacy = content.match(/<!-- skills-version:(\d+) -->/);
+  return legacy ? legacy[1] : null;
 }
 
 /**
@@ -146,6 +185,12 @@ function findSkillFiles(
  * Silently refresh installed skill files if remote versions are newer.
  * Called at MCP server startup. Non-blocking — any error (offline, 401,
  * partial install) is caught and the existing files are left in place.
+ *
+ * Phase 3b: per-skill compare. Each skill_resource row carries its own
+ * monotonic `version`. The mcp-server fetches each skill's `/v1/skills/<name>`
+ * once, reads the per-skill `skillVersion` from the response, and rewrites
+ * only the local files that are behind. An admin bumping `hmy` no longer
+ * triggers a re-fetch of `hmy-plan`, `hmy-cleanup`, etc.
  */
 export async function refreshSkills(): Promise<void> {
   try {
@@ -179,21 +224,25 @@ export async function refreshSkills(): Promise<void> {
     }
     if (skillFiles.length === 0) return;
 
-    const remoteMajor = Number.parseInt(
-      versionInfo.version.split(".")[0] ?? "",
-      10,
-    );
-    if (!Number.isFinite(remoteMajor)) return;
-
     let updated = false;
     for (const { name, filePath } of skillFiles) {
       try {
         const currentContent = readFileSync(filePath, "utf-8");
         const localVersion = parseSkillVersion(currentContent);
-        if (localVersion !== null && Number(localVersion) >= remoteMajor) {
+
+        // Fetch first so we can read the authoritative per-skill version
+        // from the response. Cheaper than a separate version probe per skill.
+        const fetched = await client.fetchSkill(name);
+        const remoteVersion = fetched.skillVersion;
+
+        if (
+          remoteVersion !== undefined &&
+          localVersion !== null &&
+          Number(localVersion) >= remoteVersion
+        ) {
           continue;
         }
-        const fetched = await client.fetchSkill(name);
+
         const newContent = buildSkillFile(fetched);
         const dir = dirname(filePath);
         if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
@@ -205,7 +254,7 @@ export async function refreshSkills(): Promise<void> {
       }
     }
     if (updated) {
-      console.error(`Harmony: Updated skills to v${versionInfo.version}`);
+      console.error("Harmony: Refreshed skills from server");
     }
   } catch {
     // Non-blocking — offline / 401 / partial install all fall through here.