@gethmy/mcp 2.8.0 → 2.8.2

package/dist/lib/api-client.js

@@ -724,6 +724,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,
@@ -1076,6 +1157,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);
   }
@@ -1433,6 +1536,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "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

@@ -1,4 +1,8 @@
-import { getDisplayLinkType } from "@harmony/shared";
+import {
+  type Comment,
+  getDisplayLinkType,
+  serializeCommentThread,
+} from "@harmony/shared";
 import { getApiKey, getApiUrl } from "./config.js";
 
 export interface ApiResponse<T = unknown> {
@@ -454,6 +458,7 @@ export class HarmonyApiClient {
       description?: string;
       priority?: string;
       assigneeId?: string;
+      planId?: string;
     },
   ): Promise<{ card: unknown }> {
     return this.request("POST", "/cards", { projectId, ...data });
@@ -616,6 +621,46 @@ export class HarmonyApiClient {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
 
+  // ============ COMMENT OPERATIONS ============
+
+  async addComment(
+    cardId: string,
+    body: string,
+    opts?: {
+      commentType?: string;
+      supersedesId?: string;
+      confirmsId?: string;
+      agentSessionId?: string;
+    },
+  ): Promise<{ comment: unknown }> {
+    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: string,
+    opts?: { limit?: number; offset?: number },
+  ): Promise<{ comments: unknown[] }> {
+    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: string,
+    updates: { body?: string; pinned?: boolean; resolve?: boolean },
+  ): Promise<{ comment: unknown }> {
+    return this.request("PATCH", `/comments/${commentId}`, updates);
+  }
+
   // ============ AGENT CONTEXT OPERATIONS ============
 
   async startAgentSession(
@@ -1447,6 +1492,26 @@ export class HarmonyApiClient {
       assemblyId,
     });
 
+    // Append the card's comment thread (people + agents). This is the central
+    // injection point: every caller of harmony_generate_prompt (daemon, Claude
+    // Code, in-app builder) gets the recency-ordered thread + conflict rule.
+    // Best-effort — never fail prompt generation on a comments fetch error.
+    try {
+      const { comments } = await this.getComments(options.cardId, {
+        limit: 200,
+      });
+      if (Array.isArray(comments) && comments.length > 0) {
+        const section = serializeCommentThread(comments as Comment[], {
+          heading: "Comments",
+          maxComments: 40,
+        });
+        if (section) result.prompt = `${result.prompt}\n\n${section}`;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] comments fetch failed: ${msg}`);
+    }
+
     // AGP P2: persist a session-linked snapshot. Best-effort — never fail
     // prompt generation just because logging didn't land.
     try {

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"],
     },
@@ -630,6 +636,72 @@ export const TOOLS = {
     },
   },
 
+  // Comment operations
+  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"],
+    },
+  },
+
   // Context operations
   harmony_list_workspaces: {
     description: "List all workspaces the user has access to",
@@ -1781,7 +1853,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 +1937,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 };
     }
@@ -2168,6 +2243,71 @@ async function handleToolCall(
       return { success: true };
     }
 
+    // Comment operations
+    case "harmony_add_comment": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const body = z.string().min(1).max(10_000).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 client.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 client.getComments(cardId, { limit, offset });
+      return { success: true, ...result };
+    }
+
+    case "harmony_update_comment": {
+      const commentId = z.string().uuid().parse(args.commentId);
+      const updates: { body?: string; pinned?: boolean; resolve?: boolean } =
+        {};
+      if (args.body !== undefined) {
+        updates.body = z.string().min(1).max(10_000).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 client.updateComment(commentId, updates);
+      return { success: true, ...result };
+    }
+
     // Context operations
     case "harmony_list_workspaces": {
       const result = await client.listWorkspaces();
@@ -3383,17 +3523,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(