@gethmy/mcp 2.9.6 → 2.9.8

package/README.md

@@ -5,8 +5,8 @@ Enables AI coding agents (Claude Code, OpenAI Codex, Cursor) to interact with yo
 
 ## Features
 
-- **56 MCP Tools** for full board control, knowledge graph, and workflow plans
-- **5 Global Skills** — `/hmy`, `/hmy-plan`, `/hmy-cleanup`, `/hmy-standup`, `/hmy-memory-prune`, served from the DB-backed [skill hub](../../docs/skills.md) with auto-update and admin-managed versioning
+- **70 MCP Tools** for full board control, knowledge graph, and workflow plans
+- **7 Global Skills** — `/hmy`, `/hmy-plan`, `/hmy-cleanup`, `/hmy-standup`, `/hmy-memory-prune`, `/hmy-upgrade`, `/hmy-review`, served from the DB-backed [skill hub](../../docs/skills.md) with auto-update and admin-managed versioning
 - **Knowledge Graph Memory** — Phase 1 surface: hybrid retrieval (vector + lexical + RRF), session-scoped working memory, activity feed. See [docs/memory.md](../../docs/memory.md)
 - **GSD Workflow Plans** - plan/execute/verify/done lifecycle with auto card creation
 - **Card Linking** - create relationships between cards (blocks, relates_to, duplicates, is_part_of)
@@ -89,7 +89,7 @@ If you prefer to configure manually (e.g., in Claude.ai's UI):
 1. Get an API key from [Harmony](https://gethmy.com/user/keys)
 2. In Claude.ai, add a remote MCP server with URL `https://mcp.gethmy.com/mcp`
 3. Set the Authorization header to `Bearer hmy_your_key_here`
-4. All 56 Harmony tools become available in your conversation
+4. All 70 Harmony tools become available in your conversation
 
 **Session management** is automatic - sessions have a 1-hour TTL and are created/renewed transparently.
 
@@ -150,7 +150,7 @@ npx @gethmy/mcp serve              # Start MCP server
 
 ## Skills
 
-Five global skills ship with the MCP server and are installed automatically by `npx @gethmy/mcp setup`. They live in the `skill_resource` Postgres table, are fetched via `GET /v1/skills/<name>`, and render-time composed with a shared auto-update preamble.
+Seven global skills ship with the MCP server and are installed automatically by `npx @gethmy/mcp setup`. They live in the `skill_resource` Postgres table, are fetched via `GET /v1/skills/<name>`, and render-time composed with a shared auto-update preamble.
 
 For the full skill hub architecture (storage, versioning, auto-update, admin management), see [docs/skills.md](../../docs/skills.md).
 

package/dist/cli.js

@@ -1385,7 +1385,6 @@ import {
   ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-
 // ../harmony-shared/dist/cardLinks.js
 var LINK_TYPE_INVERSES = {
   relates_to: "relates_to",
@@ -1815,6 +1814,16 @@ class HarmonyApiClient {
   async getCardByShortId(projectId, shortId) {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
+  async bulkGetCards(projectId, shortIds) {
+    return this.request("POST", `/projects/${projectId}/cards/bulk-get`, {
+      shortIds
+    });
+  }
+  async bulkArchiveCards(projectId, shortIds) {
+    return this.request("POST", `/projects/${projectId}/cards/bulk-archive`, {
+      shortIds
+    });
+  }
   async searchCards(query, options) {
     const params = new URLSearchParams({ q: query });
     if (options?.projectId) {
@@ -1849,6 +1858,9 @@ class HarmonyApiClient {
   async getCardExternalLinks(cardId) {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
+  async classifyCard(cardId) {
+    return this.request("POST", `/cards/${cardId}/classify`);
+  }
   async createColumn(projectId, name) {
     return this.request("POST", "/columns", { projectId, name });
   }
@@ -1910,6 +1922,9 @@ class HarmonyApiClient {
   async flushActivityLog(cardId, data) {
     return this.request("POST", `/cards/${cardId}/agent-activity-log`, data);
   }
+  async appendAgentRunEvents(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/agent-run-events`, data);
+  }
   async getActivityLog(cardId, sessionId) {
     return this.request("GET", `/cards/${cardId}/agent-activity-log?sessionId=${sessionId}`);
   }
@@ -3680,6 +3695,34 @@ var TOOLS = {
       required: ["shortId"]
     }
   },
+  harmony_bulk_get_cards: {
+    description: "Fetch multiple cards by short id in one call. Returns compact summaries " + "(id, shortId, title, column, priority, assignee, labels, archived) plus " + "any short ids not found. Requires project context. Prefer this over " + "repeated harmony_get_card_by_short_id when referencing multiple cards.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        shortIds: {
+          type: "array",
+          items: { type: "number" },
+          description: "Card short ids, e.g. [400, 401, 402]. Max 100 per call."
+        }
+      },
+      required: ["shortIds"]
+    }
+  },
+  harmony_bulk_archive_cards: {
+    description: "Archive (soft-delete) multiple cards by short id in one call. Best-effort: " + "returns { succeeded: number[], failed: [{shortId, reason}] }. Archived " + "cards can be restored with unarchive. Requires project context.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        shortIds: {
+          type: "array",
+          items: { type: "number" },
+          description: "Card short ids to archive, e.g. [400, 401]. Max 100 per call."
+        }
+      },
+      required: ["shortIds"]
+    }
+  },
   harmony_create_column: {
     description: "Create a new column in a project",
     inputSchema: {
@@ -3844,6 +3887,16 @@ var TOOLS = {
       required: ["cardId"]
     }
   },
+  harmony_classify_card: {
+    description: "Classify a card with the LLM classifier: sets `intent` (plan/think/implement/review), `complexity_score` (0-10), and `model_tier` (simple/advanced/research), stamps `classified_at`, and applies the canonical type label (feature/bug/idea). Use this right after creating a card (e.g. in the `hmy-new` flow) so it's classified in-flow instead of waiting for it to surface on the web board. Idempotent — safe to re-run. Never touches the user-owned `model_override`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID" }
+      },
+      required: ["cardId"]
+    }
+  },
   harmony_get_card_external_links: {
     description: "Get external URL references attached to a card (links to docs, gists, dashboards, etc.).",
     inputSchema: {
@@ -5169,6 +5222,18 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.getCardByShortId(projectId, shortId);
       return { success: true, ...result };
     }
+    case "harmony_bulk_get_cards": {
+      const shortIds = z.array(z.number().int().positive()).min(1).max(100).parse(args.shortIds);
+      const projectId = getProjectId();
+      const result = await client3.bulkGetCards(projectId, shortIds);
+      return { success: true, ...result };
+    }
+    case "harmony_bulk_archive_cards": {
+      const shortIds = z.array(z.number().int().positive()).min(1).max(100).parse(args.shortIds);
+      const projectId = getProjectId();
+      const result = await client3.bulkArchiveCards(projectId, shortIds);
+      return { success: true, ...result };
+    }
     case "harmony_create_column": {
       const name2 = z.string().min(1).max(100).parse(args.name);
       const projectId = args.projectId || getProjectId();
@@ -5299,6 +5364,11 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.getCardExternalLinks(cardId);
       return result;
     }
+    case "harmony_classify_card": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const result = await client3.classifyCard(cardId);
+      return result;
+    }
     case "harmony_create_subtask": {
       const cardId = z.string().uuid().parse(args.cardId);
       const title = z.string().min(1).max(500).parse(args.title);
@@ -7473,12 +7543,23 @@ async function resolveProjectSlug(apiKey, slug) {
     }
   });
   if (response.status === 404)
-    return null;
+    return { status: "not_found" };
+  if (response.status === 409) {
+    const data2 = await response.json().catch(() => ({}));
+    return {
+      status: "ambiguous",
+      candidates: Array.isArray(data2.candidates) ? data2.candidates : []
+    };
+  }
   if (!response.ok) {
     throw new Error(`Failed to resolve project slug: ${response.status}`);
   }
   const data = await response.json();
-  return { workspaceId: data.workspaceId, projectId: data.projectId };
+  return {
+    status: "found",
+    workspaceId: data.workspaceId,
+    projectId: data.projectId
+  };
 }
 async function getAgentFiles(agentId, cwd, installMode = "global") {
   const home = homedir6();
@@ -7760,12 +7841,13 @@ only for unattended CI where you accept that risk.`));
         options: [
           {
             value: "browser",
-            label: "Sign in with your browser",
-            hint: "recommended — secure, no key handling"
+            label: "Sign in or create an account in your browser",
+            hint: "recommended — new or existing users, no key handling"
           },
           {
             value: "create",
-            label: "Create a free account"
+            label: "Create an account here in the terminal",
+            hint: "no browser"
           },
           {
             value: "apikey",
@@ -8002,14 +8084,23 @@ ${colors.dim(url)}`);
   let selectedProjectId = selectedProjectIdFromSignup || options.projectId;
   let selectedWorkspaceName = selectedWorkspaceNameFromSignup;
   let selectedProjectName = selectedProjectNameFromSignup;
+  let ambiguousCandidates;
   if (options.projectSlug && apiKey && (!selectedWorkspaceId || !selectedProjectId)) {
     spinner3.start(`Resolving project slug "${options.projectSlug}"...`);
     try {
       const resolved = await resolveProjectSlug(apiKey, options.projectSlug);
-      if (resolved) {
+      if (resolved.status === "found") {
         selectedWorkspaceId = selectedWorkspaceId || resolved.workspaceId;
         selectedProjectId = selectedProjectId || resolved.projectId;
         spinner3.stop(colors.success(`Resolved "${options.projectSlug}"`));
+      } else if (resolved.status === "ambiguous") {
+        ambiguousCandidates = resolved.candidates;
+        spinner3.stop(colors.warning(`Slug "${options.projectSlug}" is ambiguous — it exists in multiple workspaces`));
+        const list = resolved.candidates.map((c) => `  • ${c.workspaceName ?? c.workspaceId}`).join(`
+`);
+        p3.log.warning(`"${options.projectSlug}" matches projects in multiple workspaces:
+${list}
+Specify the workspace with --workspace <id>, or select one below.`);
       } else {
         spinner3.stop(colors.warning(`No project found for slug "${options.projectSlug}"`));
       }
@@ -8033,12 +8124,15 @@ ${colors.dim(url)}`);
     }
     if (needsContext && workspaces.length > 0) {
       if (!selectedWorkspaceId) {
-        const workspaceOptions = workspaces.map((ws) => ({
+        const candidateIds = new Set((ambiguousCandidates ?? []).map((c) => c.workspaceId));
+        const pickable = candidateIds.size > 0 ? workspaces.filter((ws) => candidateIds.has(ws.id)) : workspaces;
+        const workspaceChoices = pickable.length > 0 ? pickable : workspaces;
+        const workspaceOptions = workspaceChoices.map((ws) => ({
           value: ws.id,
           label: ws.name
         }));
         const workspaceSelection = await p3.select({
-          message: "Select workspace",
+          message: candidateIds.size > 0 ? `Select workspace for "${options.projectSlug}"` : "Select workspace",
           options: workspaceOptions
         });
         if (p3.isCancel(workspaceSelection)) {
@@ -8048,6 +8142,12 @@ ${colors.dim(url)}`);
         selectedWorkspaceId = workspaceSelection;
       }
       selectedWorkspaceName = workspaces.find((w) => w.id === selectedWorkspaceId)?.name;
+      if (!selectedProjectId) {
+        const chosenCandidate = ambiguousCandidates?.find((c) => c.workspaceId === selectedWorkspaceId);
+        if (chosenCandidate) {
+          selectedProjectId = chosenCandidate.projectId;
+        }
+      }
       spinner3.start("Fetching projects...");
       let projects = [];
       try {
@@ -8073,6 +8173,8 @@ ${colors.dim(url)}`);
         }
         selectedProjectId = projectSelection;
         selectedProjectName = projects.find((p4) => p4.id === selectedProjectId)?.name;
+      } else if (selectedProjectId && !selectedProjectName) {
+        selectedProjectName = projects.find((p4) => p4.id === selectedProjectId)?.name;
       }
     }
   }
@@ -8297,6 +8399,11 @@ ${colors.dim(url)}`);
       console.log(`    ${colors.brand("Cursor:")} MCP tools available automatically`);
     }
     console.log("");
+    console.log(`  ${colors.bold("Next steps:")}`);
+    console.log(`    1. Open Claude Code and say: ${colors.highlight('"Show me my board"')}`);
+    console.log(`    2. Create a card: ${colors.highlight('"Create a card called Auth token refresh"')}`);
+    console.log(`    3. Start the daemon: ${colors.highlight("npx @gethmy/agent")}`);
+    console.log("");
     console.log(`  ${colors.dim("Add to new project: npx @gethmy/mcp setup")}`);
     console.log(`  ${colors.dim("Need help? Visit https://app.gethmy.com/docs/mcp")}`);
   }

package/dist/index.js

@@ -1380,7 +1380,6 @@ import {
   ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-
 // ../harmony-shared/dist/cardLinks.js
 var LINK_TYPE_INVERSES = {
   relates_to: "relates_to",
@@ -1810,6 +1809,16 @@ class HarmonyApiClient {
   async getCardByShortId(projectId, shortId) {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
+  async bulkGetCards(projectId, shortIds) {
+    return this.request("POST", `/projects/${projectId}/cards/bulk-get`, {
+      shortIds
+    });
+  }
+  async bulkArchiveCards(projectId, shortIds) {
+    return this.request("POST", `/projects/${projectId}/cards/bulk-archive`, {
+      shortIds
+    });
+  }
   async searchCards(query, options) {
     const params = new URLSearchParams({ q: query });
     if (options?.projectId) {
@@ -1844,6 +1853,9 @@ class HarmonyApiClient {
   async getCardExternalLinks(cardId) {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
+  async classifyCard(cardId) {
+    return this.request("POST", `/cards/${cardId}/classify`);
+  }
   async createColumn(projectId, name) {
     return this.request("POST", "/columns", { projectId, name });
   }
@@ -1905,6 +1917,9 @@ class HarmonyApiClient {
   async flushActivityLog(cardId, data) {
     return this.request("POST", `/cards/${cardId}/agent-activity-log`, data);
   }
+  async appendAgentRunEvents(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/agent-run-events`, data);
+  }
   async getActivityLog(cardId, sessionId) {
     return this.request("GET", `/cards/${cardId}/agent-activity-log?sessionId=${sessionId}`);
   }
@@ -3675,6 +3690,34 @@ var TOOLS = {
       required: ["shortId"]
     }
   },
+  harmony_bulk_get_cards: {
+    description: "Fetch multiple cards by short id in one call. Returns compact summaries " + "(id, shortId, title, column, priority, assignee, labels, archived) plus " + "any short ids not found. Requires project context. Prefer this over " + "repeated harmony_get_card_by_short_id when referencing multiple cards.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        shortIds: {
+          type: "array",
+          items: { type: "number" },
+          description: "Card short ids, e.g. [400, 401, 402]. Max 100 per call."
+        }
+      },
+      required: ["shortIds"]
+    }
+  },
+  harmony_bulk_archive_cards: {
+    description: "Archive (soft-delete) multiple cards by short id in one call. Best-effort: " + "returns { succeeded: number[], failed: [{shortId, reason}] }. Archived " + "cards can be restored with unarchive. Requires project context.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        shortIds: {
+          type: "array",
+          items: { type: "number" },
+          description: "Card short ids to archive, e.g. [400, 401]. Max 100 per call."
+        }
+      },
+      required: ["shortIds"]
+    }
+  },
   harmony_create_column: {
     description: "Create a new column in a project",
     inputSchema: {
@@ -3839,6 +3882,16 @@ var TOOLS = {
       required: ["cardId"]
     }
   },
+  harmony_classify_card: {
+    description: "Classify a card with the LLM classifier: sets `intent` (plan/think/implement/review), `complexity_score` (0-10), and `model_tier` (simple/advanced/research), stamps `classified_at`, and applies the canonical type label (feature/bug/idea). Use this right after creating a card (e.g. in the `hmy-new` flow) so it's classified in-flow instead of waiting for it to surface on the web board. Idempotent — safe to re-run. Never touches the user-owned `model_override`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID" }
+      },
+      required: ["cardId"]
+    }
+  },
   harmony_get_card_external_links: {
     description: "Get external URL references attached to a card (links to docs, gists, dashboards, etc.).",
     inputSchema: {
@@ -5164,6 +5217,18 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.getCardByShortId(projectId, shortId);
       return { success: true, ...result };
     }
+    case "harmony_bulk_get_cards": {
+      const shortIds = z.array(z.number().int().positive()).min(1).max(100).parse(args.shortIds);
+      const projectId = getProjectId();
+      const result = await client3.bulkGetCards(projectId, shortIds);
+      return { success: true, ...result };
+    }
+    case "harmony_bulk_archive_cards": {
+      const shortIds = z.array(z.number().int().positive()).min(1).max(100).parse(args.shortIds);
+      const projectId = getProjectId();
+      const result = await client3.bulkArchiveCards(projectId, shortIds);
+      return { success: true, ...result };
+    }
     case "harmony_create_column": {
       const name2 = z.string().min(1).max(100).parse(args.name);
       const projectId = args.projectId || getProjectId();
@@ -5294,6 +5359,11 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.getCardExternalLinks(cardId);
       return result;
     }
+    case "harmony_classify_card": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const result = await client3.classifyCard(cardId);
+      return result;
+    }
     case "harmony_create_subtask": {
       const cardId = z.string().uuid().parse(args.cardId);
       const title = z.string().min(1).max(500).parse(args.title);

package/dist/lib/api-client.js

@@ -833,7 +833,6 @@ var init_oauth_refresh = __esm(() => {
   init_config();
   init_oauth_login();
 });
-
 // ../harmony-shared/dist/cardLinks.js
 var LINK_TYPE_INVERSES = {
   relates_to: "relates_to",
@@ -1263,6 +1262,16 @@ class HarmonyApiClient {
   async getCardByShortId(projectId, shortId) {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
+  async bulkGetCards(projectId, shortIds) {
+    return this.request("POST", `/projects/${projectId}/cards/bulk-get`, {
+      shortIds
+    });
+  }
+  async bulkArchiveCards(projectId, shortIds) {
+    return this.request("POST", `/projects/${projectId}/cards/bulk-archive`, {
+      shortIds
+    });
+  }
   async searchCards(query, options) {
     const params = new URLSearchParams({ q: query });
     if (options?.projectId) {
@@ -1297,6 +1306,9 @@ class HarmonyApiClient {
   async getCardExternalLinks(cardId) {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
+  async classifyCard(cardId) {
+    return this.request("POST", `/cards/${cardId}/classify`);
+  }
   async createColumn(projectId, name) {
     return this.request("POST", "/columns", { projectId, name });
   }
@@ -1358,6 +1370,9 @@ class HarmonyApiClient {
   async flushActivityLog(cardId, data) {
     return this.request("POST", `/cards/${cardId}/agent-activity-log`, data);
   }
+  async appendAgentRunEvents(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/agent-run-events`, data);
+  }
   async getActivityLog(cardId, sessionId) {
     return this.request("GET", `/cards/${cardId}/agent-activity-log?sessionId=${sessionId}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.9.6",
+  "version": "2.9.8",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -1,4 +1,5 @@
 import {
+  type AgentRunEventDraft,
   type Comment,
   getDisplayLinkType,
   serializeCommentThread,
@@ -151,6 +152,18 @@ export interface CardExternalLinkRow {
   created_at: string;
 }
 
+/** Result of the classify-card classifier (card #415). Any field may be null
+ * if the LLM didn't return a usable value. `model_override` is never touched. */
+export interface CardClassificationResult {
+  type: "feature" | "bug" | "idea" | null;
+  intent: "plan" | "think" | "implement" | "review" | null;
+  complexity_score: number | null;
+  model_tier: "simple" | "advanced" | "research" | null;
+  classified_at: string;
+  applied_type_label_id: string | null;
+  reasoning: string | null;
+}
+
 export class HarmonyApiClient {
   private apiKey: string;
   private apiUrl: string;
@@ -570,6 +583,39 @@ export class HarmonyApiClient {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
 
+  async bulkGetCards(
+    projectId: string,
+    shortIds: number[],
+  ): Promise<{
+    cards: Array<{
+      id: string;
+      shortId: number;
+      title: string;
+      column: string | null;
+      priority: string | null;
+      assignee: string | null;
+      labels: string[];
+      archived: boolean;
+    }>;
+    notFound: number[];
+  }> {
+    return this.request("POST", `/projects/${projectId}/cards/bulk-get`, {
+      shortIds,
+    });
+  }
+
+  async bulkArchiveCards(
+    projectId: string,
+    shortIds: number[],
+  ): Promise<{
+    succeeded: number[];
+    failed: Array<{ shortId: number; reason: string }>;
+  }> {
+    return this.request("POST", `/projects/${projectId}/cards/bulk-archive`, {
+      shortIds,
+    });
+  }
+
   async searchCards(
     query: string,
     options?: { projectId?: string },
@@ -635,6 +681,12 @@ export class HarmonyApiClient {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
 
+  async classifyCard(
+    cardId: string,
+  ): Promise<{ classification: CardClassificationResult }> {
+    return this.request("POST", `/cards/${cardId}/classify`);
+  }
+
   // ============ COLUMN OPERATIONS ============
 
   async createColumn(
@@ -847,6 +899,20 @@ export class HarmonyApiClient {
     return this.request("POST", `/cards/${cardId}/agent-activity-log`, data);
   }
 
+  /**
+   * Append events to a run's agent_run_events stream (card #417). Send drafts in
+   * chronological order — the server's seq trigger assigns the monotonic per-run order.
+   */
+  async appendAgentRunEvents(
+    cardId: string,
+    data: {
+      sessionId: string;
+      events: (AgentRunEventDraft & { createdAt?: string })[];
+    },
+  ): Promise<{ inserted: number }> {
+    return this.request("POST", `/cards/${cardId}/agent-run-events`, data);
+  }
+
   async getActivityLog(
     cardId: string,
     sessionId: string,

package/src/server.ts

@@ -469,6 +469,43 @@ export const TOOLS = {
       required: ["shortId"],
     },
   },
+  harmony_bulk_get_cards: {
+    description:
+      "Fetch multiple cards by short id in one call. Returns compact summaries " +
+      "(id, shortId, title, column, priority, assignee, labels, archived) plus " +
+      "any short ids not found. Requires project context. Prefer this over " +
+      "repeated harmony_get_card_by_short_id when referencing multiple cards.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        shortIds: {
+          type: "array",
+          items: { type: "number" },
+          description:
+            "Card short ids, e.g. [400, 401, 402]. Max 100 per call.",
+        },
+      },
+      required: ["shortIds"],
+    },
+  },
+  harmony_bulk_archive_cards: {
+    description:
+      "Archive (soft-delete) multiple cards by short id in one call. Best-effort: " +
+      "returns { succeeded: number[], failed: [{shortId, reason}] }. Archived " +
+      "cards can be restored with unarchive. Requires project context.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        shortIds: {
+          type: "array",
+          items: { type: "number" },
+          description:
+            "Card short ids to archive, e.g. [400, 401]. Max 100 per call.",
+        },
+      },
+      required: ["shortIds"],
+    },
+  },
 
   // Column operations
   harmony_create_column: {
@@ -649,6 +686,17 @@ export const TOOLS = {
       required: ["cardId"],
     },
   },
+  harmony_classify_card: {
+    description:
+      "Classify a card with the LLM classifier: sets `intent` (plan/think/implement/review), `complexity_score` (0-10), and `model_tier` (simple/advanced/research), stamps `classified_at`, and applies the canonical type label (feature/bug/idea). Use this right after creating a card (e.g. in the `hmy-new` flow) so it's classified in-flow instead of waiting for it to surface on the web board. Idempotent — safe to re-run. Never touches the user-owned `model_override`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID" },
+      },
+      required: ["cardId"],
+    },
+  },
   harmony_get_card_external_links: {
     description:
       "Get external URL references attached to a card (links to docs, gists, dashboards, etc.).",
@@ -2241,6 +2289,28 @@ async function handleToolCall(
       return { success: true, ...result };
     }
 
+    case "harmony_bulk_get_cards": {
+      const shortIds = z
+        .array(z.number().int().positive())
+        .min(1)
+        .max(100)
+        .parse(args.shortIds);
+      const projectId = getProjectId();
+      const result = await client.bulkGetCards(projectId, shortIds);
+      return { success: true, ...result };
+    }
+
+    case "harmony_bulk_archive_cards": {
+      const shortIds = z
+        .array(z.number().int().positive())
+        .min(1)
+        .max(100)
+        .parse(args.shortIds);
+      const projectId = getProjectId();
+      const result = await client.bulkArchiveCards(projectId, shortIds);
+      return { success: true, ...result };
+    }
+
     // Column operations
     case "harmony_create_column": {
       const name = z.string().min(1).max(100).parse(args.name);
@@ -2425,6 +2495,12 @@ async function handleToolCall(
       return result;
     }
 
+    case "harmony_classify_card": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const result = await client.classifyCard(cardId);
+      return result;
+    }
+
     // Subtask operations
     case "harmony_create_subtask": {
       const cardId = z.string().uuid().parse(args.cardId);

package/src/tui/setup.ts

@@ -331,14 +331,31 @@ async function fetchProjects(
   return data.projects || [];
 }
 
+export interface SlugCandidate {
+  workspaceId: string;
+  workspaceName: string | null;
+  projectId: string;
+}
+
+/**
+ * Outcome of resolving a project slug. `ambiguous` means the same slug exists
+ * in more than one of the caller's workspaces (HTTP 409) — common for bare
+ * web-onboarded slugs like "my-first-board" when a user belongs to several
+ * teams. The caller must disambiguate rather than treat it as not-found.
+ */
+export type ResolveSlugResult =
+  | { status: "found"; workspaceId: string; projectId: string }
+  | { status: "not_found" }
+  | { status: "ambiguous"; candidates: SlugCandidate[] };
+
 /**
  * Resolve a project slug to {workspaceId, projectId}. Used by
  * `npx @gethmy/mcp setup <slug>` so users don't have to copy raw UUIDs.
  */
-async function resolveProjectSlug(
+export async function resolveProjectSlug(
   apiKey: string,
   slug: string,
-): Promise<{ workspaceId: string; projectId: string } | null> {
+): Promise<ResolveSlugResult> {
   const response = await fetch(
     `${API_URL}/v1/projects/resolve/${encodeURIComponent(slug)}`,
     {
@@ -350,13 +367,26 @@ async function resolveProjectSlug(
     },
   );
 
-  if (response.status === 404) return null;
+  if (response.status === 404) return { status: "not_found" };
+  // 409 = slug matches projects in multiple workspaces. The body carries the
+  // candidate workspaces so we can tell the user which ones to pick from.
+  if (response.status === 409) {
+    const data = await response.json().catch(() => ({}));
+    return {
+      status: "ambiguous",
+      candidates: Array.isArray(data.candidates) ? data.candidates : [],
+    };
+  }
   if (!response.ok) {
     throw new Error(`Failed to resolve project slug: ${response.status}`);
   }
 
   const data = await response.json();
-  return { workspaceId: data.workspaceId, projectId: data.projectId };
+  return {
+    status: "found",
+    workspaceId: data.workspaceId,
+    projectId: data.projectId,
+  };
 }
 
 export interface FileToWrite {
@@ -753,12 +783,13 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
         options: [
           {
             value: "browser",
-            label: "Sign in with your browser",
-            hint: "recommended — secure, no key handling",
+            label: "Sign in or create an account in your browser",
+            hint: "recommended — new or existing users, no key handling",
           },
           {
             value: "create",
-            label: "Create a free account",
+            label: "Create an account here in the terminal",
+            hint: "no browser",
           },
           {
             value: "apikey",
@@ -1056,6 +1087,10 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   let selectedWorkspaceName: string | undefined =
     selectedWorkspaceNameFromSignup;
   let selectedProjectName: string | undefined = selectedProjectNameFromSignup;
+  // When a slug is ambiguous, the candidate workspaces (each already carrying
+  // the matching projectId) narrow the interactive picker below to just those
+  // workspaces instead of every workspace the user belongs to.
+  let ambiguousCandidates: SlugCandidate[] | undefined;
 
   // Resolve project slug shorthand (e.g. `npx @gethmy/mcp setup harmony-6590761b`).
   // Slug wins over --workspace/--project flags only when those aren't already set
@@ -1068,10 +1103,28 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
     spinner.start(`Resolving project slug "${options.projectSlug}"...`);
     try {
       const resolved = await resolveProjectSlug(apiKey, options.projectSlug);
-      if (resolved) {
+      if (resolved.status === "found") {
         selectedWorkspaceId = selectedWorkspaceId || resolved.workspaceId;
         selectedProjectId = selectedProjectId || resolved.projectId;
         spinner.stop(colors.success(`Resolved "${options.projectSlug}"`));
+      } else if (resolved.status === "ambiguous") {
+        // Same slug in multiple workspaces — don't silently pick one. Surface
+        // the candidates so the user knows to specify a workspace; interactive
+        // context selection below still lets them recover in a TTY, narrowed to
+        // just these workspaces.
+        ambiguousCandidates = resolved.candidates;
+        spinner.stop(
+          colors.warning(
+            `Slug "${options.projectSlug}" is ambiguous — it exists in multiple workspaces`,
+          ),
+        );
+        const list = resolved.candidates
+          .map((c) => `  • ${c.workspaceName ?? c.workspaceId}`)
+          .join("\n");
+        p.log.warning(
+          `"${options.projectSlug}" matches projects in multiple workspaces:\n${list}\n` +
+            "Specify the workspace with --workspace <id>, or select one below.",
+        );
       } else {
         spinner.stop(
           colors.warning(`No project found for slug "${options.projectSlug}"`),
@@ -1108,15 +1161,28 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
     }
 
     if (needsContext && workspaces.length > 0) {
-      // Select workspace
+      // Select workspace. When the slug was ambiguous, restrict the choices to
+      // the candidate workspaces so the user picks among the ones that actually
+      // contain the slug (falling back to all workspaces if none still match).
       if (!selectedWorkspaceId) {
-        const workspaceOptions = workspaces.map((ws) => ({
+        const candidateIds = new Set(
+          (ambiguousCandidates ?? []).map((c) => c.workspaceId),
+        );
+        const pickable =
+          candidateIds.size > 0
+            ? workspaces.filter((ws) => candidateIds.has(ws.id))
+            : workspaces;
+        const workspaceChoices = pickable.length > 0 ? pickable : workspaces;
+        const workspaceOptions = workspaceChoices.map((ws) => ({
           value: ws.id,
           label: ws.name,
         }));
 
         const workspaceSelection = await p.select({
-          message: "Select workspace",
+          message:
+            candidateIds.size > 0
+              ? `Select workspace for "${options.projectSlug}"`
+              : "Select workspace",
           options: workspaceOptions,
         });
 
@@ -1132,6 +1198,17 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
         (w) => w.id === selectedWorkspaceId,
       )?.name;
 
+      // For an ambiguous slug, the chosen workspace already pins the project —
+      // each candidate carries its projectId — so skip the project picker.
+      if (!selectedProjectId) {
+        const chosenCandidate = ambiguousCandidates?.find(
+          (c) => c.workspaceId === selectedWorkspaceId,
+        );
+        if (chosenCandidate) {
+          selectedProjectId = chosenCandidate.projectId;
+        }
+      }
+
       // Fetch and select project
       spinner.start("Fetching projects...");
       let projects: Project[] = [];
@@ -1167,6 +1244,12 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
         selectedProjectName = projects.find(
           (p) => p.id === selectedProjectId,
         )?.name;
+      } else if (selectedProjectId && !selectedProjectName) {
+        // Project was pre-resolved (e.g. from an ambiguous-slug candidate) so
+        // the picker was skipped — backfill the name for the summary display.
+        selectedProjectName = projects.find(
+          (p) => p.id === selectedProjectId,
+        )?.name;
       }
     }
   }
@@ -1517,6 +1600,18 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
       );
     }
 
+    console.log("");
+    console.log(`  ${colors.bold("Next steps:")}`);
+    console.log(
+      `    1. Open Claude Code and say: ${colors.highlight('"Show me my board"')}`,
+    );
+    console.log(
+      `    2. Create a card: ${colors.highlight('"Create a card called Auth token refresh"')}`,
+    );
+    console.log(
+      `    3. Start the daemon: ${colors.highlight("npx @gethmy/agent")}`,
+    );
+
     console.log("");
     console.log(`  ${colors.dim("Add to new project: npx @gethmy/mcp setup")}`);
     console.log(