@gethmy/mcp 2.2.1 → 2.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"
@@ -69,6 +69,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@harmony/memory": "workspace:*",
     "@types/node": "^25.5.0",
     "typescript": "^6.0.1"
   }

package/src/auto-session.ts

@@ -6,7 +6,7 @@
  * after 10 minutes of inactivity or when a different card is worked on.
  *
  * Agent identity is resolved from the MCP client's `initialize` handshake
- * (clientInfo.name), so "Claude Code", "Cursor", "Windsurf", etc. are
+ * (clientInfo.name), so "Claude Code", "Cursor", "Codex", etc. are
  * detected automatically — no hardcoded fallback needed.
  */
 

package/src/cli.ts

@@ -29,6 +29,11 @@ program
   .command("serve")
   .description("Start the MCP server (stdio transport)")
   .action(async () => {
+    if (!isConfigured()) {
+      console.error("No API key configured.");
+      console.error("Run: npx @gethmy/mcp setup");
+      process.exit(1);
+    }
     await refreshSkills();
     const server = new HarmonyMCPServer();
     await server.run();
@@ -147,6 +152,8 @@ program
   .option("-p, --project <id>", "Set project context")
   .option("--skip-context", "Skip workspace/project selection")
   .option("--skip-docs", "Skip project docs scaffold/verification")
+  .option("--new", "Create a new account (skip the choice prompt)")
+  .option("-n, --name <name>", "Full name (for account creation)")
   .action(async (options) => {
     await runSetup({
       force: options.force,
@@ -162,6 +169,8 @@ program
       projectId: options.project,
       skipContext: options.skipContext,
       skipDocs: options.skipDocs,
+      newAccount: options.new,
+      name: options.name,
     });
   });
 

package/src/onboard.ts

@@ -0,0 +1,93 @@
+import { requestWithBearer, signupUser } from "./api-client.js";
+import { getApiUrl } from "./config.js";
+
+export interface OnboardParams {
+  email: string;
+  password: string;
+  fullName: string;
+  workspaceName?: string;
+  projectName?: string;
+  template?: string;
+  keyName?: string;
+  apiUrl?: string;
+}
+
+export interface OnboardResult {
+  user: { id: string; email: string; full_name: string };
+  workspace: { id: string; name: string; slug: string; created_at: string };
+  project: { id: string; name: string; slug: string };
+  columns: unknown[];
+  apiKey: {
+    rawKey: string;
+    prefix: string;
+  };
+}
+
+export async function onboardNewUser(
+  params: OnboardParams,
+): Promise<OnboardResult> {
+  const {
+    email,
+    password,
+    fullName,
+    workspaceName = `${fullName}'s Workspace`,
+    projectName = "My First Board",
+    template = "kanban",
+    keyName = "mcp-agent",
+    apiUrl = getApiUrl(),
+  } = params;
+
+  // 1. Signup
+  const signupResult = await signupUser(apiUrl, {
+    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,
+    template,
+  });
+
+  // 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,
+  });
+
+  return {
+    user: signupResult.user,
+    workspace: workspaceResult.workspace,
+    project: projectResult.project,
+    columns: projectResult.columns,
+    apiKey: {
+      rawKey: keyResult.rawKey,
+      prefix: keyResult.apiKey.prefix,
+    },
+  };
+}

package/src/server.ts

@@ -23,7 +23,6 @@ import {
 import {
   getClient,
   type HarmonyApiClient,
-  requestWithBearer,
   resetClient,
   signupUser,
 } from "./api-client.js";
@@ -59,6 +58,7 @@ import {
 } from "./context-assembly.js";
 import { autoExpandGraph } from "./graph-expansion.js";
 import { runLifecycleMaintenance } from "./lifecycle-maintenance.js";
+import { onboardNewUser } from "./onboard.js";
 import type { PromptVariant } from "./prompt-builder.js";
 
 /**
@@ -273,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: {
@@ -420,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: {
@@ -1971,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>,
@@ -2041,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;
@@ -2178,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 };
     }
@@ -2363,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);
                 }
               }
             }
@@ -2571,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)
@@ -2616,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
@@ -2655,6 +2743,7 @@ async function handleToolCall(
 
       return {
         success: true,
+        ...(sessionEndError && { sessionEndError }),
         movedTo,
         learningsExtracted: pipelineResult.learningsExtracted,
         feedbackAdjusted: pipelineResult.feedbackAdjusted,
@@ -3773,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.`,
       };
     }

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