@gethmy/mcp 2.8.0 → 2.8.2

package/dist/index.js

@@ -932,6 +932,87 @@ function getDisplayLinkType(linkType, direction) {
     return linkType;
   return LINK_TYPE_INVERSES[linkType];
 }
+// ../harmony-shared/dist/commentSerializer.js
+var CONFLICT_INSTRUCTION = "When two comments conflict, prefer the latest created_at, UNLESS a later " + "comment explicitly confirms or restates the earlier finding. Evaluate " + "substance, not just recency. Cite the comment id(s) you relied on.";
+function authorLabel(c) {
+  if (c.author_type === "agent")
+    return "AI agent";
+  return c.author?.full_name || c.author?.email || "teammate";
+}
+function criticalIds(comments) {
+  const keep = new Set;
+  for (const c of comments) {
+    if (c.comment_type === "decision")
+      keep.add(c.id);
+    if (c.supersedes_id) {
+      keep.add(c.id);
+      keep.add(c.supersedes_id);
+    }
+    if (c.confirms_id) {
+      keep.add(c.id);
+      keep.add(c.confirms_id);
+    }
+  }
+  return keep;
+}
+function serializeCommentThread(comments, options = {}) {
+  const { heading = "Conversation", includeInstructions = true, activity = [], maxComments } = options;
+  const visible = comments.filter((c) => !c.deleted_at).slice().sort((a, b) => a.created_at.localeCompare(b.created_at));
+  if (visible.length === 0)
+    return "";
+  const indexById = new Map;
+  visible.forEach((c, i) => {
+    indexById.set(c.id, i + 1);
+  });
+  let rendered = visible;
+  let elidedCount = 0;
+  if (maxComments && visible.length > maxComments) {
+    const keep = criticalIds(visible);
+    const recentThreshold = visible.length - maxComments;
+    rendered = visible.filter((c, i) => i >= recentThreshold || keep.has(c.id));
+    elidedCount = visible.length - rendered.length;
+  }
+  const ref = (id) => {
+    const n = indexById.get(id);
+    return n ? `#${n}` : `#${id.slice(0, 8)}`;
+  };
+  const lines = [];
+  if (elidedCount > 0) {
+    lines.push({
+      at: visible[0]?.created_at ?? "",
+      text: `(${elidedCount} earlier comment(s) omitted for brevity)`
+    });
+  }
+  for (const c of rendered) {
+    const tags = [];
+    if (c.edited_at)
+      tags.push("edited");
+    if (c.supersedes_id)
+      tags.push(`supersedes ${ref(c.supersedes_id)}`);
+    if (c.confirms_id)
+      tags.push(`confirms ${ref(c.confirms_id)}`);
+    if (c.resolved_at)
+      tags.push("resolved");
+    const tagStr = tags.length ? ` | ${tags.join(" | ")}` : "";
+    const header = `[${ref(c.id)} | ${c.author_type} | ${authorLabel(c)} | ${c.comment_type} | ${c.created_at}${tagStr}]`;
+    lines.push({ at: c.created_at, text: `${header}
+${c.body.trim()}` });
+  }
+  for (const a of activity) {
+    const actor = a.actor ? `${a.actor} ` : "";
+    lines.push({ at: a.at, text: `· (system) ${a.at} — ${actor}${a.text}` });
+  }
+  lines.sort((a, b) => a.at.localeCompare(b.at));
+  const body = lines.map((l) => l.text).join(`
+
+`);
+  const instruction = includeInstructions ? `
+
+${CONFLICT_INSTRUCTION}` : "";
+  return `## ${heading} (oldest → newest)
+
+${body}${instruction}`;
+}
 // ../harmony-shared/dist/constants.js
 var TIMINGS = {
   SEARCH_DEBOUNCE: 300,
@@ -1469,6 +1550,28 @@ class HarmonyApiClient {
   async deleteSubtask(subtaskId) {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
+  async addComment(cardId, body, opts) {
+    return this.request("POST", `/cards/${cardId}/comments`, {
+      body,
+      authorType: "agent",
+      commentType: opts?.commentType,
+      supersedesId: opts?.supersedesId,
+      confirmsId: opts?.confirmsId,
+      agentSessionId: opts?.agentSessionId
+    });
+  }
+  async getComments(cardId, opts) {
+    const qs = new URLSearchParams;
+    if (opts?.limit != null)
+      qs.set("limit", String(opts.limit));
+    if (opts?.offset != null)
+      qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/cards/${cardId}/comments${suffix}`);
+  }
+  async updateComment(commentId, updates) {
+    return this.request("PATCH", `/comments/${commentId}`, updates);
+  }
   async startAgentSession(cardId, data) {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
   }
@@ -1826,6 +1929,24 @@ class HarmonyApiClient {
       assembledContext: assembledContextStr,
       assemblyId
     });
+    try {
+      const { comments } = await this.getComments(options.cardId, {
+        limit: 200
+      });
+      if (Array.isArray(comments) && comments.length > 0) {
+        const section = serializeCommentThread(comments, {
+          heading: "Comments",
+          maxComments: 40
+        });
+        if (section)
+          result.prompt = `${result.prompt}
+
+${section}`;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] comments fetch failed: ${msg}`);
+    }
     try {
       await this.recordPromptHistory({
         cardId: cardData.id,
@@ -2374,6 +2495,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 +2920,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"]
     }
@@ -2836,6 +3249,66 @@ var TOOLS = {
       required: ["subtaskId"]
     }
   },
+  harmony_add_comment: {
+    description: "Post a comment on a card as the agent. Use this to converse with the human in the open: report progress, ask a question, record a decision, or note a finding — instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. When the thread conflicts, prefer the latest comment unless a later one confirms an earlier finding; cite the comment id(s) you relied on.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID to comment on" },
+        body: { type: "string", description: "Comment body (Markdown)" },
+        commentType: {
+          type: "string",
+          enum: [
+            "message",
+            "progress",
+            "question",
+            "blocker",
+            "decision",
+            "summary",
+            "finding"
+          ],
+          description: "Type of comment. 'question'/'blocker' signal you need a human; default 'message'."
+        },
+        supersedesId: {
+          type: "string",
+          description: "Comment id this comment corrects/updates"
+        },
+        confirmsId: {
+          type: "string",
+          description: "Comment id this comment reaffirms"
+        }
+      },
+      required: ["cardId", "body"]
+    }
+  },
+  harmony_get_comments: {
+    description: "Get the comment thread on a card (oldest → newest). Returns human + agent comments with author, type, edited/resolved state, and supersede/confirm links. Read this before acting so you weigh later comments over earlier ones they contradict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string" },
+        limit: { type: "number" },
+        offset: { type: "number" }
+      },
+      required: ["cardId"]
+    }
+  },
+  harmony_update_comment: {
+    description: "Update one of your own comments: edit the body, pin it, or resolve a question/blocker once it has been answered.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        commentId: { type: "string" },
+        body: { type: "string" },
+        pinned: { type: "boolean" },
+        resolve: {
+          type: "boolean",
+          description: "Mark (true) or clear (false) the resolved state"
+        }
+      },
+      required: ["commentId"]
+    }
+  },
   harmony_list_workspaces: {
     description: "List all workspaces the user has access to",
     inputSchema: {
@@ -3826,7 +4299,7 @@ function registerHandlers(server, deps) {
           {
             uri,
             mimeType: "text/markdown",
-            text: fetched.content
+            text: stripSkillPreamble(fetched.content)
           }
         ]
       };
@@ -3876,7 +4349,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 };
     }
@@ -4096,6 +4570,49 @@ async function handleToolCall(name, args, deps) {
       await client3.deleteSubtask(subtaskId);
       return { success: true };
     }
+    case "harmony_add_comment": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const body = z.string().min(1).max(1e4).parse(args.body);
+      const commentType = args.commentType !== undefined ? z.enum([
+        "message",
+        "progress",
+        "question",
+        "blocker",
+        "decision",
+        "summary",
+        "finding"
+      ]).parse(args.commentType) : undefined;
+      const supersedesId = args.supersedesId !== undefined ? z.string().uuid().parse(args.supersedesId) : undefined;
+      const confirmsId = args.confirmsId !== undefined ? z.string().uuid().parse(args.confirmsId) : undefined;
+      const result = await client3.addComment(cardId, body, {
+        commentType,
+        supersedesId,
+        confirmsId
+      });
+      return { success: true, ...result };
+    }
+    case "harmony_get_comments": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const limit = args.limit !== undefined ? z.number().int().min(1).max(500).parse(args.limit) : undefined;
+      const offset = args.offset !== undefined ? z.number().int().min(0).parse(args.offset) : undefined;
+      const result = await client3.getComments(cardId, { limit, offset });
+      return { success: true, ...result };
+    }
+    case "harmony_update_comment": {
+      const commentId = z.string().uuid().parse(args.commentId);
+      const updates = {};
+      if (args.body !== undefined) {
+        updates.body = z.string().min(1).max(1e4).parse(args.body);
+      }
+      if (args.pinned !== undefined) {
+        updates.pinned = z.boolean().parse(args.pinned);
+      }
+      if (args.resolve !== undefined) {
+        updates.resolve = z.boolean().parse(args.resolve);
+      }
+      const result = await client3.updateComment(commentId, updates);
+      return { success: true, ...result };
+    }
     case "harmony_list_workspaces": {
       const result = await client3.listWorkspaces();
       return { success: true, ...result };
@@ -4902,13 +5419,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);