@gethmy/mcp 2.8.0 → 2.8.1

package/dist/index.js

@@ -2374,6 +2374,294 @@ async function onboardNewUser(params) {
   };
 }
 
+// src/skills.ts
+import {
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync4,
+  renameSync,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { dirname, join as join4 } from "node:path";
+
+// src/hmy-config.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join3 } from "node:path";
+var DEFAULTS = { updateCheck: true, pin: null };
+function getHmyConfigPath() {
+  return join3(homedir2(), ".hmy", "config.yaml");
+}
+function loadHmyConfig() {
+  const path = getHmyConfigPath();
+  if (!existsSync3(path))
+    return { ...DEFAULTS };
+  try {
+    return parseHmyConfig(readFileSync3(path, "utf-8"));
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+function parseHmyConfig(text) {
+  const cfg = { ...DEFAULTS };
+  for (const rawLine of text.split(`
+`)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#"))
+      continue;
+    const sep2 = line.indexOf(":");
+    if (sep2 === -1)
+      continue;
+    const key = line.slice(0, sep2).trim();
+    let value = line.slice(sep2 + 1).trim();
+    const hash = value.indexOf(" #");
+    if (hash !== -1)
+      value = value.slice(0, hash).trim();
+    value = value.replace(/^["']|["']$/g, "");
+    switch (key) {
+      case "update_check":
+        cfg.updateCheck = value !== "false";
+        break;
+      case "pin":
+      case "pin_version":
+        cfg.pin = value || null;
+        break;
+    }
+  }
+  return cfg;
+}
+
+// src/skills.ts
+var HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
+
+Start work on a Harmony card. Card reference: $ARGUMENTS
+
+## 1. Find & Fetch Card
+
+Parse the reference and fetch the card:
+- \`#42\` or \`42\` → \`harmony_get_card_by_short_id\` with \`shortId: 42\`
+- UUID → \`harmony_get_card\` with \`cardId\`
+- Name/text → \`harmony_search_cards\` with \`query\`
+
+## 2. Get Board State
+
+Call \`harmony_get_board\` to get columns and labels. From the response:
+- Find the "In Progress" (or "Progress") column ID
+- Find the "agent" label ID
+
+## 3. Setup Card for Work
+
+Execute these in sequence:
+1. \`harmony_move_card\` → Move to "In Progress" column
+2. \`harmony_add_label_to_card\` → Add "agent" label
+3. \`harmony_start_agent_session\`:
+   - \`cardId\`: Card UUID
+   - \`agentIdentifier\`: Your agent identifier
+   - \`agentName\`: Your agent name
+   - \`currentTask\`: "Analyzing card requirements"
+
+## 4. Generate Work Prompt
+
+Call \`harmony_generate_prompt\` with:
+- \`cardId\` or \`shortId\` (+ \`projectId\` if using shortId)
+- \`variant\`: Select based on task:
+  - \`"execute"\` (default) → Clear tasks, bug fixes, well-defined work
+  - \`"analysis"\` → Complex features, unclear requirements
+  - \`"draft"\` → Medium complexity, want feedback first
+
+The generated prompt provides role framing, focus areas, subtasks, linked cards, and suggested outputs.
+
+## 5. Display Card Summary
+
+Show the user: Card title, short ID, role, priority, labels, due date, description, and subtasks.
+
+## 6. Implement Solution
+
+Work on the card following the generated prompt's guidance. Update progress at milestones:
+- \`harmony_update_agent_progress\` with \`progressPercent\` (0-100), \`currentTask\`, \`status\`, \`blockers\`
+
+**Progress checkpoints:** 20% (exploration), 50% (implementation), 80% (testing), 100% (done)
+
+## 7. Complete Work
+
+When finished:
+1. \`harmony_end_agent_session\` with \`status: "completed"\`, \`progressPercent: 100\`
+2. \`harmony_move_card\` to "Review" column
+3. Summarize accomplishments
+
+If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
+
+## Key Tools Reference
+
+**Cards:** \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\`, \`harmony_create_card\`, \`harmony_update_card\`, \`harmony_move_card\`, \`harmony_delete_card\`, \`harmony_assign_card\`
+
+**Subtasks:** \`harmony_create_subtask\`, \`harmony_toggle_subtask\`, \`harmony_delete_subtask\`
+
+**Labels:** \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\`, \`harmony_create_label\`
+
+**Links:** \`harmony_add_link_to_card\`, \`harmony_remove_link_from_card\`, \`harmony_get_card_links\`
+
+**Board:** \`harmony_get_board\`, \`harmony_list_projects\`, \`harmony_get_context\`, \`harmony_set_project_context\`
+
+**Sessions:** \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\`, \`harmony_get_agent_session\`
+
+**AI:** \`harmony_generate_prompt\`, \`harmony_process_command\`
+`;
+function buildSkillFile(skill) {
+  const content = stripSkillPreamble(skill.content);
+  if (skill.skillVersion !== undefined && !hasMetadataVersion(content)) {
+    return injectMetadataVersion(content, skill.skillVersion);
+  }
+  return content;
+}
+var PREAMBLE_START = "<!-- hmy-skills-preamble:start -->";
+var PREAMBLE_END = "<!-- hmy-skills-preamble:end -->";
+function stripSkillPreamble(content) {
+  const start = content.indexOf(PREAMBLE_START);
+  const end = content.indexOf(PREAMBLE_END);
+  if (start === -1 || end === -1 || end < start)
+    return content;
+  const stripped = content.slice(0, start) + content.slice(end + PREAMBLE_END.length);
+  return `${stripped.replace(/\n{3,}/g, `
+
+`).replace(/\s+$/, "")}
+`;
+}
+function atomicWrite(filePath, content) {
+  const dir = dirname(filePath);
+  if (!existsSync4(dir))
+    mkdirSync3(dir, { recursive: true });
+  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync3(tmp, content);
+  renameSync(tmp, filePath);
+}
+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 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 = [];
+  for (const filePath of paths) {
+    if (!existsSync4(filePath))
+      continue;
+    for (const name of knownNames) {
+      if (filePath.includes(`/${name}/`) || filePath.includes(`/${name}.md`)) {
+        results.push({ name, filePath });
+        break;
+      }
+    }
+  }
+  return results;
+}
+var HMY_DIR = join4(homedir3(), ".hmy");
+var HMY_VERSION_FILE = join4(HMY_DIR, "VERSION");
+var LAST_CHECK_FILE = join4(HMY_DIR, "last-update-check");
+var CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+function checkedRecently(now = Date.now()) {
+  try {
+    if (!existsSync4(LAST_CHECK_FILE))
+      return false;
+    const ts = Number.parseInt(readFileSync4(LAST_CHECK_FILE, "utf-8").trim(), 10);
+    if (!Number.isFinite(ts))
+      return false;
+    return now - ts < CHECK_TTL_MS;
+  } catch {
+    return false;
+  }
+}
+function recordCheck(now = Date.now()) {
+  try {
+    if (!existsSync4(HMY_DIR))
+      mkdirSync3(HMY_DIR, { recursive: true });
+    writeFileSync3(LAST_CHECK_FILE, String(now));
+  } catch {}
+}
+async function refreshSkills(opts = {}) {
+  try {
+    if (!isConfigured())
+      return { updated: false };
+    const cfg = loadHmyConfig();
+    if (!cfg.updateCheck || cfg.pin)
+      return { updated: false };
+    if (!opts.force && checkedRecently())
+      return { updated: false };
+    const status = areSkillsInstalled();
+    if (!status.installed)
+      return { updated: false };
+    const client3 = new HarmonyApiClient;
+    const versionInfo = await client3.fetchSkillsVersion();
+    recordCheck();
+    const skillFiles = findSkillFiles(status.paths, versionInfo.skills);
+    if (skillFiles.length > 0) {
+      const samplePath = skillFiles[0].filePath;
+      for (const name of versionInfo.skills) {
+        if (skillFiles.some((sf) => sf.name === name))
+          continue;
+        let siblingPath;
+        if (samplePath.endsWith("SKILL.md")) {
+          const parentDir = dirname(dirname(samplePath));
+          siblingPath = `${parentDir}/${name}/SKILL.md`;
+        } else {
+          const parentDir = dirname(samplePath);
+          siblingPath = `${parentDir}/${name}.md`;
+        }
+        if (existsSync4(siblingPath)) {
+          skillFiles.push({ name, filePath: siblingPath });
+        }
+      }
+    }
+    if (skillFiles.length === 0)
+      return { updated: false };
+    let updated = false;
+    for (const { name, filePath } of skillFiles) {
+      try {
+        const currentContent = readFileSync4(filePath, "utf-8");
+        const localVersion = parseSkillVersion(currentContent);
+        const fetched = await client3.fetchSkill(name);
+        const remoteVersion = fetched.skillVersion;
+        if (remoteVersion !== undefined && localVersion !== null && Number(localVersion) >= remoteVersion) {
+          continue;
+        }
+        atomicWrite(filePath, buildSkillFile(fetched));
+        updated = true;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Harmony: skill "${name}" refresh failed: ${msg}`);
+      }
+    }
+    if (updated) {
+      try {
+        atomicWrite(HMY_VERSION_FILE, versionInfo.version);
+      } catch {}
+      console.error("Harmony: Refreshed skills from server");
+    }
+    return { updated };
+  } catch {
+    return { updated: false };
+  }
+}
+
 // src/server.ts
 var memorySessions = new Map;
 function parseLabelList(raw) {
@@ -2511,7 +2799,11 @@ var TOOLS = {
           enum: ["low", "medium", "high", "urgent"],
           description: "Priority level"
         },
-        assigneeId: { type: "string", description: "Assignee user ID" }
+        assigneeId: { type: "string", description: "Assignee user ID" },
+        planId: {
+          type: "string",
+          description: "Plan ID to link this card to (optional). Links the card to that plan via its plan_id."
+        }
       },
       required: ["title"]
     }
@@ -3826,7 +4118,7 @@ function registerHandlers(server, deps) {
           {
             uri,
             mimeType: "text/markdown",
-            text: fetched.content
+            text: stripSkillPreamble(fetched.content)
           }
         ]
       };
@@ -3876,7 +4168,8 @@ async function handleToolCall(name, args, deps) {
         columnId: args.columnId,
         description: args.description,
         priority: args.priority,
-        assigneeId: args.assigneeId
+        assigneeId: args.assigneeId,
+        planId: args.planId
       });
       return { success: true, ...result };
     }
@@ -4902,13 +5195,16 @@ function createConfigDeps() {
 class HarmonyMCPServer {
   server;
   constructor() {
-    this.server = new Server({ name: "@gethmy/mcp", version: "2.0.0" }, { capabilities: { tools: {}, resources: {} } });
+    this.server = new Server({ name: "@gethmy/mcp", version: "2.0.0" }, { capabilities: { tools: {}, resources: { listChanged: true } } });
     registerHandlers(this.server, createConfigDeps());
   }
-  async run() {
+  async run(opts = {}) {
     const transport = new StdioServerTransport;
     await this.server.connect(transport);
     console.error("Harmony MCP server running on stdio");
+    if (opts.skillsUpdated) {
+      this.server.sendResourceListChanged().catch(() => {});
+    }
     const configDeps = createConfigDeps();
     initAutoSession(async (client3, cardId, status) => {
       await runEndSessionPipeline(client3, configDeps, cardId, status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"
@@ -60,7 +60,7 @@
     "serve:remote": "bun src/remote.ts",
     "dev": "bun --watch src/index.ts",
     "test": "bun run test:unit && bun run test:integration",
-    "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__/tool-dispatch.test.ts src/__tests__/mcp-integration.test.ts",
+    "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"

package/src/api-client.ts

@@ -454,6 +454,7 @@ export class HarmonyApiClient {
       description?: string;
       priority?: string;
       assigneeId?: string;
+      planId?: string;
     },
   ): Promise<{ card: unknown }> {
     return this.request("POST", "/cards", { projectId, ...data });

package/src/cli.ts

@@ -34,9 +34,9 @@ program
       console.error("Run: npx @gethmy/mcp setup");
       process.exit(1);
     }
-    await refreshSkills();
+    const { updated } = await refreshSkills();
     const server = new HarmonyMCPServer();
-    await server.run();
+    await server.run({ skillsUpdated: updated });
   });
 
 program

package/src/hmy-config.ts

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * User-facing knobs for the skill auto-update, stored at `~/.hmy/config.yaml`.
+ *
+ * This file used to be read only by the bash auto-update preamble. Now that
+ * the MCP server owns auto-update (refreshSkills at `serve` startup), the
+ * server reads it directly. We intentionally avoid a YAML dependency: the file
+ * is a flat `key: value` list, so a tiny line parser is enough and keeps the
+ * install footprint small.
+ */
+export interface HmyConfig {
+  /** Master switch. `update_check: false` disables auto-update entirely. */
+  updateCheck: boolean;
+  /**
+   * Freeze to a specific skills version. When set, the server skips
+   * auto-update so the user stays on whatever is currently installed.
+   */
+  pin: string | null;
+}
+
+const DEFAULTS: HmyConfig = { updateCheck: true, pin: null };
+
+export function getHmyConfigPath(): string {
+  return join(homedir(), ".hmy", "config.yaml");
+}
+
+/** Read `~/.hmy/config.yaml`, falling back to defaults on any error. */
+export function loadHmyConfig(): HmyConfig {
+  const path = getHmyConfigPath();
+  if (!existsSync(path)) return { ...DEFAULTS };
+  try {
+    return parseHmyConfig(readFileSync(path, "utf-8"));
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+/**
+ * Parse the flat `key: value` config body. Unknown keys are ignored;
+ * surrounding quotes and inline comments after a `#` are stripped. Exported
+ * for tests.
+ */
+export function parseHmyConfig(text: string): HmyConfig {
+  const cfg: HmyConfig = { ...DEFAULTS };
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const sep = line.indexOf(":");
+    if (sep === -1) continue;
+    const key = line.slice(0, sep).trim();
+    let value = line.slice(sep + 1).trim();
+    // Drop trailing inline comment, then surrounding quotes.
+    const hash = value.indexOf(" #");
+    if (hash !== -1) value = value.slice(0, hash).trim();
+    value = value.replace(/^["']|["']$/g, "");
+    switch (key) {
+      case "update_check":
+        cfg.updateCheck = value !== "false";
+        break;
+      case "pin":
+      case "pin_version":
+        cfg.pin = value || null;
+        break;
+    }
+  }
+  return cfg;
+}

package/src/server.ts

@@ -48,6 +48,7 @@ import {
   sessionScopeFor,
 } from "./memory-session.js";
 import { onboardNewUser } from "./onboard.js";
+import { stripSkillPreamble } from "./skills.js";
 
 /**
  * Dependencies injected into tool handlers.
@@ -286,6 +287,11 @@ export const TOOLS = {
           description: "Priority level",
         },
         assigneeId: { type: "string", description: "Assignee user ID" },
+        planId: {
+          type: "string",
+          description:
+            "Plan ID to link this card to (optional). Links the card to that plan via its plan_id.",
+        },
       },
       required: ["title"],
     },
@@ -1781,7 +1787,9 @@ export function registerHandlers(server: Server, deps: ToolDeps): void {
           {
             uri,
             mimeType: "text/markdown",
-            text: fetched.content,
+            // Strip the legacy auto-update bash block if a stale render still
+            // carries it — the agent shouldn't be handed curl→chmod→exec.
+            text: stripSkillPreamble(fetched.content),
           },
         ],
       };
@@ -1863,6 +1871,7 @@ async function handleToolCall(
         description: args.description as string | undefined,
         priority: args.priority as string | undefined,
         assigneeId: args.assigneeId as string | undefined,
+        planId: args.planId as string | undefined,
       });
       return { success: true, ...result };
     }
@@ -3383,17 +3392,32 @@ export class HarmonyMCPServer {
   constructor() {
     this.server = new Server(
       { name: "@gethmy/mcp", version: "2.0.0" },
-      { capabilities: { tools: {}, resources: {} } },
+      // resources.listChanged lets us notify the client when a startup skill
+      // refresh rewrites SKILL.md files, so it re-reads them this session.
+      { capabilities: { tools: {}, resources: { listChanged: true } } },
     );
 
     registerHandlers(this.server, createConfigDeps());
   }
 
-  async run() {
+  /**
+   * @param opts.skillsUpdated  Set when the pre-connect skill refresh
+   *   (cli.ts) rewrote files. Triggers a resources/list_changed notification
+   *   once the transport is connected so the client picks up the new skills.
+   */
+  async run(opts: { skillsUpdated?: boolean } = {}) {
     const transport = new StdioServerTransport();
     await this.server.connect(transport);
     console.error("Harmony MCP server running on stdio");
 
+    if (opts.skillsUpdated) {
+      // Client is connected now — tell it the skill resources changed.
+      this.server.sendResourceListChanged().catch(() => {
+        // Best-effort: a missed notification just means the new skills load
+        // on the next session instead of this one.
+      });
+    }
+
     // Initialize auto-session tracking with MCP client identity detection
     const configDeps = createConfigDeps();
     initAutoSession(