@gethmy/mcp 2.2.0 → 2.2.2

package/src/server.ts

@@ -23,7 +23,6 @@ import {
 import {
   getClient,
   type HarmonyApiClient,
-  requestWithBearer,
   resetClient,
   signupUser,
 } from "./api-client.js";
@@ -59,13 +58,8 @@ import {
 } from "./context-assembly.js";
 import { autoExpandGraph } from "./graph-expansion.js";
 import { runLifecycleMaintenance } from "./lifecycle-maintenance.js";
-import {
-  type CardData,
-  type ColumnData,
-  generatePrompt,
-  type MemoryData,
-  type PromptVariant,
-} from "./prompt-builder.js";
+import { onboardNewUser } from "./onboard.js";
+import type { PromptVariant } from "./prompt-builder.js";
 
 /**
  * Dependencies injected into tool handlers.
@@ -279,18 +273,24 @@ const TOOLS = {
     },
   },
   harmony_move_card: {
-    description: "Move a card to a different column or position",
+    description:
+      "Move a card to a different column or position. Provide either columnId (UUID) or columnName (e.g. 'Review', 'Done').",
     inputSchema: {
       type: "object",
       properties: {
         cardId: { type: "string", description: "Card ID to move" },
-        columnId: { type: "string", description: "Target column ID" },
+        columnId: { type: "string", description: "Target column ID (UUID)" },
+        columnName: {
+          type: "string",
+          description:
+            "Target column name (e.g. 'To Do', 'In Progress', 'Review', 'Done'). Used if columnId is not provided.",
+        },
         position: {
           type: "number",
           description: "Position in column (0-indexed)",
         },
       },
-      required: ["cardId", "columnId"],
+      required: ["cardId"],
     },
   },
   harmony_archive_card: {
@@ -426,14 +426,22 @@ const TOOLS = {
     },
   },
   harmony_add_label_to_card: {
-    description: "Add a label to a card",
+    description:
+      "Add a label to a card. Provide labelId directly, or labelName to look up (or auto-create) the label by name.",
     inputSchema: {
       type: "object",
       properties: {
         cardId: { type: "string" },
-        labelId: { type: "string" },
+        labelId: {
+          type: "string",
+          description: "Label ID (optional if labelName provided)",
+        },
+        labelName: {
+          type: "string",
+          description: "Label name — will look up or create if not found",
+        },
       },
-      required: ["cardId", "labelId"],
+      required: ["cardId"],
     },
   },
   harmony_remove_label_from_card: {
@@ -1977,6 +1985,27 @@ export function registerHandlers(server: Server, deps: ToolDeps): void {
   });
 }
 
+/** Resolve a column name to its ID. Prefers exact match, falls back to substring. */
+async function resolveColumnByName(
+  client: HarmonyApiClient,
+  projectId: string,
+  columnName: string,
+): Promise<{ id: string; name: string }> {
+  const board = await client.getBoard(projectId, { summary: true });
+  const columns = board.columns as Array<{ id: string; name: string }>;
+  const lower = columnName.toLowerCase();
+  const col =
+    columns.find((c) => c.name.toLowerCase() === lower) ||
+    columns.find((c) => c.name.toLowerCase().includes(lower));
+  if (!col) {
+    const available = columns.map((c) => c.name).join(", ");
+    throw new Error(
+      `Column "${columnName}" not found. Available columns: ${available}`,
+    );
+  }
+  return col;
+}
+
 async function handleToolCall(
   name: string,
   args: Record<string, unknown>,
@@ -2047,21 +2076,41 @@ async function handleToolCall(
 
     case "harmony_move_card": {
       const cardId = z.string().uuid().parse(args.cardId);
-      const columnId = z.string().uuid().parse(args.columnId);
       const position =
         args.position !== undefined
           ? z.number().int().min(0).parse(args.position)
           : undefined;
+
+      // Resolve columnId — accept UUID directly or resolve from columnName
+      let columnId: string;
+      let resolvedProjectId: string | undefined;
+      if (args.columnId) {
+        columnId = z.string().uuid().parse(args.columnId);
+      } else if (args.columnName) {
+        const columnName = z.string().parse(args.columnName);
+        const { card: cardForProject } = await client.getCard(cardId);
+        resolvedProjectId = (cardForProject as { project_id?: string })
+          ?.project_id;
+        if (!resolvedProjectId) throw new Error("Card has no project");
+        const col = await resolveColumnByName(
+          client,
+          resolvedProjectId,
+          columnName,
+        );
+        columnId = col.id;
+      } else {
+        throw new Error("Either columnId or columnName is required");
+      }
+
       const result = await client.moveCard(cardId, columnId, position);
 
       // Auto-end active agent session when moving to Review or Done
       let sessionEnded = false;
       try {
         const { card } = result as { card: { project_id?: string } };
-        if (card?.project_id) {
-          const board = await client.getBoard(card.project_id, {
-            summary: true,
-          });
+        const projectId = card?.project_id || resolvedProjectId;
+        if (projectId) {
+          const board = await client.getBoard(projectId, { summary: true });
           const columns = board.columns as Array<{
             id: string;
             name: string;
@@ -2184,7 +2233,47 @@ async function handleToolCall(
 
     case "harmony_add_label_to_card": {
       const cardId = z.string().uuid().parse(args.cardId);
-      const labelId = z.string().uuid().parse(args.labelId);
+      let labelId = args.labelId
+        ? z.string().uuid().parse(args.labelId)
+        : undefined;
+      const labelName = args.labelName
+        ? z.string().min(1).max(100).parse(args.labelName)
+        : undefined;
+
+      // If labelName provided without labelId, look up or create the label
+      if (!labelId && labelName) {
+        const { card } = await client.getCard(cardId);
+        const projectId = (card as { project_id?: string }).project_id;
+        if (!projectId) {
+          throw new Error(
+            "Cannot resolve label by name: card has no project_id",
+          );
+        }
+        if (projectId) {
+          const board = await client.getBoard(projectId, { summary: true });
+          const labels = board.labels as Array<{
+            id: string;
+            name: string;
+          }>;
+          const existing = labels.find(
+            (l) => l.name.toLowerCase() === labelName.toLowerCase(),
+          );
+          if (existing) {
+            labelId = existing.id;
+          } else {
+            const created = await client.createLabel(projectId, {
+              name: labelName,
+              color: "#57b8a5",
+            });
+            labelId = (created as { label: { id: string } }).label.id;
+          }
+        }
+      }
+
+      if (!labelId) {
+        throw new Error("Either labelId or labelName must be provided");
+      }
+
       await client.addLabelToCard(cardId, labelId);
       return { success: true };
     }
@@ -2369,12 +2458,20 @@ async function handleToolCall(
 
             if (addLabels?.length) {
               for (const labelName of addLabels) {
-                const label = labels.find(
+                let label = labels.find(
                   (l) => l.name.toLowerCase() === labelName.toLowerCase(),
                 );
+                if (!label && projectId) {
+                  const created = await client.createLabel(projectId, {
+                    name: labelName,
+                    color: "#57b8a5",
+                  });
+                  label = (created as { label: { id: string; name: string } })
+                    .label;
+                }
                 if (label) {
                   await client.addLabelToCard(cardId, label.id);
-                  labelsAdded.push(label.name);
+                  labelsAdded.push(label.name ?? labelName);
                 }
               }
             }
@@ -2577,38 +2674,30 @@ async function handleToolCall(
       await flushMemoryActions(client, cardId);
       cleanupMemorySession(cardId);
 
-      const result = await client.endAgentSession(cardId, {
-        status: sessionStatus,
-        progressPercent: endProgressPercent,
-      });
+      // End the session — tolerate failure (e.g., session already ended or not found)
+      let result: { session: unknown } = { session: null };
+      let sessionEndError: string | null = null;
+      try {
+        result = await client.endAgentSession(cardId, {
+          status: sessionStatus,
+          progressPercent: endProgressPercent,
+        });
+      } catch (err) {
+        sessionEndError =
+          err instanceof Error ? err.message : "Failed to end session";
+      }
 
-      // Remove from auto-session tracking
+      // Remove from auto-session tracking regardless
       untrack(cardId);
 
       let movedTo: string | null = null;
-      const _learningsExtracted = 0;
 
-      // Get card info for move and learning extraction
-      let _cardTitle = "";
-      let _cardLabels: string[] = [];
-      let _cardDescription = "";
-      let _cardSubtasks: Array<{ title: string; done: boolean }> = [];
       try {
         const { card } = await client.getCard(cardId);
         const typedCard = card as {
           project_id?: string;
-          title?: string;
-          description?: string;
           labels?: Array<{ id: string; name: string }>;
-          subtasks?: Array<{ title: string; done: boolean }>;
         };
-        _cardTitle = typedCard.title || "";
-        _cardLabels = (typedCard.labels || []).map((l) => l.name);
-        _cardDescription = typedCard.description || "";
-        _cardSubtasks = (typedCard.subtasks || []).map((s) => ({
-          title: s.title,
-          done: s.done,
-        }));
         const projectId = typedCard.project_id;
 
         // Remove "agent" label when session is completed (not paused)
@@ -2622,20 +2711,13 @@ async function handleToolCall(
         }
 
         if (moveToColumn && projectId) {
-          const board = await client.getBoard(projectId, {
-            summary: true,
-          });
-          const columns = board.columns as Array<{
-            id: string;
-            name: string;
-          }>;
-          const col = columns.find((c) =>
-            c.name.toLowerCase().includes(moveToColumn.toLowerCase()),
+          const col = await resolveColumnByName(
+            client,
+            projectId,
+            moveToColumn,
           );
-          if (col) {
-            await client.moveCard(cardId, col.id);
-            movedTo = col.name;
-          }
+          await client.moveCard(cardId, col.id);
+          movedTo = col.name;
         }
       } catch {
         // Card fetch/move failed, continue
@@ -2661,6 +2743,7 @@ async function handleToolCall(
 
       return {
         success: true,
+        ...(sessionEndError && { sessionEndError }),
         movedTo,
         learningsExtracted: pipelineResult.learningsExtracted,
         feedbackAdjusted: pipelineResult.feedbackAdjusted,
@@ -2699,14 +2782,11 @@ async function handleToolCall(
 
     // Prompt generation
     case "harmony_generate_prompt": {
-      // Get card - either by UUID or short ID
-      let cardData: CardData;
-      let columnData: ColumnData | null = null;
+      // Resolve card ID — either directly or via short ID
+      let cardId: string;
 
       if (args.cardId) {
-        const cardId = z.string().uuid().parse(args.cardId);
-        const cardResult = await client.getCard(cardId);
-        cardData = cardResult.card as CardData;
+        cardId = z.string().uuid().parse(args.cardId);
       } else if (args.shortId !== undefined) {
         const shortId = z.number().int().positive().parse(args.shortId);
         const projectId =
@@ -2717,35 +2797,12 @@ async function handleToolCall(
           );
         }
         const cardResult = await client.getCardByShortId(projectId, shortId);
-        cardData = cardResult.card as CardData;
+        cardId = (cardResult.card as { id: string }).id;
       } else {
         throw new Error("Either cardId or shortId must be provided");
       }
 
-      // Try to get column info from board
-      const projectIdForBoard =
-        (args.projectId as string) ||
-        getActiveProjectId() ||
-        (cardData as unknown as { project_id: string }).project_id;
-      if (projectIdForBoard) {
-        try {
-          const board = await client.getBoard(projectIdForBoard, {
-            summary: true,
-          });
-          const columnId = (cardData as unknown as { column_id: string })
-            .column_id;
-          const column = (
-            board.columns as Array<{ id: string; name: string }>
-          ).find((col) => col.id === columnId);
-          if (column) {
-            columnData = { name: column.name };
-          }
-        } catch {
-          // Column info not available, continue without it
-        }
-      }
-
-      const variant = (args.variant as PromptVariant) || "execute";
+      // Parse MCP-specific context options
       const contextOptions: Record<string, boolean> = {};
       if (args.includeSubtasks !== undefined) {
         contextOptions.includeSubtasks =
@@ -2761,89 +2818,24 @@ async function handleToolCall(
           args.includeDescription === "true";
       }
 
-      // Assemble context using the context assembly engine
-      let assembledContextStr: string | undefined;
-      let assemblyId: string | undefined;
-      let memories: MemoryData[] | undefined;
-
-      try {
-        const workspaceId = deps.getActiveWorkspaceId();
-        if (workspaceId && cardData.title) {
-          const cardLabels = (cardData.labels || []).map((l) => l.name);
-          const taskContext = [cardData.title, cardData.description || ""]
-            .filter(Boolean)
-            .join(" ");
-
-          const assembled = await assembleContext({
-            workspaceId,
-            projectId: getActiveProjectId() || undefined,
-            taskContext,
-            cardLabels,
-            cardId: cardData.id,
-            client,
-          });
-
-          if (assembled.context) {
-            assembledContextStr = assembled.context;
-            assemblyId = assembled.manifest.assemblyId;
-            cacheManifest(assembled.manifest);
-          }
-        }
-      } catch {
-        // Context assembly failed, try legacy fallback
-        try {
-          const workspaceId = deps.getActiveWorkspaceId();
-          if (workspaceId && cardData.title) {
-            const memoryResult = await client.searchMemoryEntities(
-              workspaceId,
-              cardData.title,
-              {
-                project_id: getActiveProjectId() || undefined,
-                limit: 5,
-              },
-            );
-            if (memoryResult.entities?.length > 0) {
-              memories = memoryResult.entities.map((e: unknown) => {
-                const entity = e as {
-                  id: string;
-                  type: string;
-                  title: string;
-                  content: string;
-                  confidence: number;
-                  tags: string[];
-                };
-                return {
-                  id: entity.id,
-                  type: entity.type,
-                  title: entity.title,
-                  content: entity.content,
-                  confidence: entity.confidence,
-                  tags: entity.tags || [],
-                };
-              });
-            }
-          }
-        } catch {
-          // Memory fetch also failed, continue without memories
-        }
-      }
-
-      const result = generatePrompt({
-        card: cardData,
-        column: columnData,
-        variant,
-        contextOptions,
+      // Delegate to the shared prompt generation pipeline
+      const result = await client.generateCardPrompt({
+        cardId,
+        workspaceId: deps.getActiveWorkspaceId() || "",
+        projectId:
+          (args.projectId as string) || getActiveProjectId() || undefined,
+        variant: (args.variant as PromptVariant) || "execute",
         customConstraints: args.customConstraints as string | undefined,
-        memories,
-        assembledContext: assembledContextStr,
-        assemblyId,
+        contextOptions,
       });
 
+      // MCP-specific: cache the assembly manifest for the feedback loop
+      if (result.assemblyId) {
+        trackSessionAssembly(cardId, result.assemblyId);
+      }
+
       return {
         success: true,
-        cardId: cardData.id,
-        shortId: cardData.short_id,
-        title: cardData.title,
         ...result,
       };
     }
@@ -3037,8 +3029,7 @@ async function handleToolCall(
       // Track memory write action and flush (fire-and-forget)
       const updateMemSession = getActiveMemorySession();
       if (updateMemSession) {
-        const updateTitle =
-          (updates.title as string) || entityId.slice(0, 8);
+        const updateTitle = (updates.title as string) || entityId.slice(0, 8);
         appendMemoryAction(
           updateMemSession.cardId,
           `Updated memory: ${updateTitle}`,
@@ -3871,69 +3862,31 @@ async function handleToolCall(
       const projectName = (args.projectName as string) || "My First Project";
       const template = (args.template as string) || "kanban";
       const keyName = (args.keyName as string) || "mcp-agent";
-      const apiUrl = deps.getApiUrl();
 
-      // 1. Signup
-      const signupResult = await signupUser(apiUrl, {
+      const result = await onboardNewUser({
         email,
         password,
-        full_name: fullName,
-      });
-      const token = signupResult.session.access_token;
-
-      // 2. Create workspace
-      const workspaceResult = await requestWithBearer<{
-        workspace: {
-          id: string;
-          name: string;
-          slug: string;
-          created_at: string;
-        };
-      }>(apiUrl, token, "POST", "/workspaces", {
-        name: workspaceName,
-      });
-
-      // 3. Create project
-      const projectResult = await requestWithBearer<{
-        project: { id: string; name: string; slug: string };
-        columns: unknown[];
-      }>(apiUrl, token, "POST", "/projects", {
-        workspaceId: workspaceResult.workspace.id,
-        name: projectName,
+        fullName,
+        workspaceName,
+        projectName,
         template,
+        keyName,
+        apiUrl: deps.getApiUrl(),
       });
 
-      // 4. Generate API key
-      const keyResult = await requestWithBearer<{
-        apiKey: {
-          id: string;
-          name: string;
-          prefix: string;
-          created_at: string;
-        };
-        rawKey: string;
-      }>(apiUrl, token, "POST", "/api-keys", {
-        name: keyName,
-      });
-
-      // 5. Save config
-      deps.saveConfig({ apiKey: keyResult.rawKey });
-      deps.setActiveWorkspace(workspaceResult.workspace.id);
-      deps.setActiveProject(projectResult.project.id);
-
-      // 6. Reset client so singleton picks up new key
+      // Save config and reset client
+      deps.saveConfig({ apiKey: result.apiKey.rawKey });
+      deps.setActiveWorkspace(result.workspace.id);
+      deps.setActiveProject(result.project.id);
       deps.resetClient();
 
       return {
         success: true,
-        user: signupResult.user,
-        workspace: workspaceResult.workspace,
-        project: projectResult.project,
-        columns: projectResult.columns,
-        apiKey: {
-          rawKey: keyResult.rawKey,
-          prefix: keyResult.apiKey.prefix,
-        },
+        user: result.user,
+        workspace: result.workspace,
+        project: result.project,
+        columns: result.columns,
+        apiKey: result.apiKey,
         message: `Onboarding complete! Account created for ${email}. Workspace "${workspaceName}" and project "${projectName}" are ready. API key saved to config.`,
       };
     }
@@ -4053,13 +4006,17 @@ export class HarmonyMCPServer {
     await this.server.connect(transport);
     console.error("Harmony MCP server running on stdio");
 
-    // Initialize auto-session tracking
+    // Initialize auto-session tracking with MCP client identity detection
     const configDeps = createConfigDeps();
     initAutoSession(
       async (client, cardId, status) => {
         await runEndSessionPipeline(client, configDeps, cardId, status);
       },
       () => getClient(),
+      () => {
+        const cv = this.server.getClientVersion();
+        return cv ? { name: cv.name, version: cv.version } : null;
+      },
     );
 
     // Graceful shutdown: end all auto-sessions

package/src/skills.ts

@@ -7,7 +7,7 @@ export const SKILLS_VERSION = "3";
 const VERSION_MARKER_PREFIX = "<!-- skills-version:";
 
 /**
- * Legacy workflow prompt used by Codex, Cursor, Windsurf agents.
+ * Legacy workflow prompt used by Codex, Cursor agents.
  * Claude Code skills use the newer SKILL_DEFINITIONS content instead.
  */
 export const HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow