@gethmy/mcp 2.9.5 → 2.9.7

package/README.md

@@ -5,7 +5,7 @@ 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
+- **69 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
 - **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

package/dist/cli.js

@@ -1815,6 +1815,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) {
@@ -3680,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: {
@@ -5169,6 +5207,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();
@@ -7473,12 +7523,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();
@@ -8002,14 +8063,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 +8103,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 +8121,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 +8152,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;
       }
     }
   }

package/dist/index.js

@@ -1810,6 +1810,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) {
@@ -3675,6 +3685,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: {
@@ -5164,6 +5202,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();

package/dist/lib/api-client.js

@@ -1263,6 +1263,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) {

package/package.json

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

package/src/api-client.ts

@@ -570,6 +570,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 },

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: {
@@ -2241,6 +2278,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);

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 {
@@ -1056,6 +1086,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 +1102,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 +1160,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 +1197,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 +1243,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;
       }
     }
   }