@gethmy/mcp 2.17.1 → 2.18.0

package/dist/cli.js

@@ -1869,6 +1869,10 @@ class HarmonyApiClient {
   async getCardByShortId(projectId, shortId) {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
+  async resolveCardByShortId(shortId, preferredProjectId) {
+    const qs = preferredProjectId ? `?preferred_project_id=${encodeURIComponent(preferredProjectId)}` : "";
+    return this.request("GET", `/cards/resolve/${shortId}${qs}`);
+  }
   async bulkGetCards(projectId, shortIds) {
     return this.request("POST", `/projects/${projectId}/cards/bulk-get`, {
       shortIds
@@ -5763,9 +5767,51 @@ async function handleToolCall(name, args, deps) {
       }
       if (hasShortId) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId = args.projectId || getProjectId();
-        const result2 = await client3.getCardByShortId(projectId, shortId);
-        return { success: true, ...result2 };
+        const explicitProjectId = args.projectId;
+        if (explicitProjectId) {
+          const result2 = await client3.getCardByShortId(explicitProjectId, shortId);
+          return { success: true, ...result2 };
+        }
+        const activeProjectId = deps.getActiveProjectId();
+        const resolved = await client3.resolveCardByShortId(shortId, activeProjectId);
+        if (resolved.kind === "found") {
+          const cardTitle = resolved.card?.title ?? `#${shortId}`;
+          const where = resolved.project.workspaceName ? `project "${resolved.project.name ?? resolved.project.id}" (workspace "${resolved.project.workspaceName}")` : `project "${resolved.project.name ?? resolved.project.id}"`;
+          const established = activeProjectId == null;
+          if (established) {
+            deps.setActiveProject(resolved.project.id);
+          }
+          return {
+            success: true,
+            card: resolved.card,
+            resolvedProject: resolved.project,
+            activeProjectId: resolved.project.id,
+            note: established ? `Resolved #${shortId} → "${cardTitle}" in ${where}. No active project was set — set to this for follow-up references.` : `Resolved #${shortId} → "${cardTitle}" in ${where} (your active project).`
+          };
+        }
+        if (resolved.kind === "not_in_preferred") {
+          const list = resolved.candidates.map((c) => `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""} (projectId: ${c.projectId})`).join(`
+`);
+          throw new Error(`#${shortId} is not in your active project (projectId: ${resolved.preferredProjectId}). ` + `It exists in ${resolved.candidates.length} other project(s) you can access:
+${list}
+
+` + `Switch with harmony_set_project_context, or pass an explicit projectId to fetch it directly.`);
+        }
+        if (resolved.kind === "ambiguous") {
+          const list = resolved.candidates.map((c) => `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""} (projectId: ${c.projectId})`).join(`
+`);
+          return {
+            success: true,
+            needsDisambiguation: true,
+            shortId,
+            candidates: resolved.candidates,
+            message: `#${shortId} exists in ${resolved.candidates.length} projects you can access:
+${list}
+
+` + `Ask which one is meant, then re-fetch with an explicit projectId ` + `(or call harmony_set_project_context first).`
+          };
+        }
+        throw new Error(resolved.searchedProjectCount === 0 ? `#${shortId} can't be resolved: no project is accessible to this connection. ` + `Check the workspace this connection is authorized for with harmony_list_workspaces.` : `Card #${shortId} was not found in any of the ${resolved.searchedProjectCount} ` + `project(s) across ${resolved.searchedWorkspaceCount} workspace(s) this connection can access. ` + `Use harmony_list_projects to see them, or pass an explicit projectId.`);
       }
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client3.getCard(cardId);

package/dist/index.js

@@ -1864,6 +1864,10 @@ class HarmonyApiClient {
   async getCardByShortId(projectId, shortId) {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
+  async resolveCardByShortId(shortId, preferredProjectId) {
+    const qs = preferredProjectId ? `?preferred_project_id=${encodeURIComponent(preferredProjectId)}` : "";
+    return this.request("GET", `/cards/resolve/${shortId}${qs}`);
+  }
   async bulkGetCards(projectId, shortIds) {
     return this.request("POST", `/projects/${projectId}/cards/bulk-get`, {
       shortIds
@@ -5758,9 +5762,51 @@ async function handleToolCall(name, args, deps) {
       }
       if (hasShortId) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId = args.projectId || getProjectId();
-        const result2 = await client3.getCardByShortId(projectId, shortId);
-        return { success: true, ...result2 };
+        const explicitProjectId = args.projectId;
+        if (explicitProjectId) {
+          const result2 = await client3.getCardByShortId(explicitProjectId, shortId);
+          return { success: true, ...result2 };
+        }
+        const activeProjectId = deps.getActiveProjectId();
+        const resolved = await client3.resolveCardByShortId(shortId, activeProjectId);
+        if (resolved.kind === "found") {
+          const cardTitle = resolved.card?.title ?? `#${shortId}`;
+          const where = resolved.project.workspaceName ? `project "${resolved.project.name ?? resolved.project.id}" (workspace "${resolved.project.workspaceName}")` : `project "${resolved.project.name ?? resolved.project.id}"`;
+          const established = activeProjectId == null;
+          if (established) {
+            deps.setActiveProject(resolved.project.id);
+          }
+          return {
+            success: true,
+            card: resolved.card,
+            resolvedProject: resolved.project,
+            activeProjectId: resolved.project.id,
+            note: established ? `Resolved #${shortId} → "${cardTitle}" in ${where}. No active project was set — set to this for follow-up references.` : `Resolved #${shortId} → "${cardTitle}" in ${where} (your active project).`
+          };
+        }
+        if (resolved.kind === "not_in_preferred") {
+          const list = resolved.candidates.map((c) => `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""} (projectId: ${c.projectId})`).join(`
+`);
+          throw new Error(`#${shortId} is not in your active project (projectId: ${resolved.preferredProjectId}). ` + `It exists in ${resolved.candidates.length} other project(s) you can access:
+${list}
+
+` + `Switch with harmony_set_project_context, or pass an explicit projectId to fetch it directly.`);
+        }
+        if (resolved.kind === "ambiguous") {
+          const list = resolved.candidates.map((c) => `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""} (projectId: ${c.projectId})`).join(`
+`);
+          return {
+            success: true,
+            needsDisambiguation: true,
+            shortId,
+            candidates: resolved.candidates,
+            message: `#${shortId} exists in ${resolved.candidates.length} projects you can access:
+${list}
+
+` + `Ask which one is meant, then re-fetch with an explicit projectId ` + `(or call harmony_set_project_context first).`
+          };
+        }
+        throw new Error(resolved.searchedProjectCount === 0 ? `#${shortId} can't be resolved: no project is accessible to this connection. ` + `Check the workspace this connection is authorized for with harmony_list_workspaces.` : `Card #${shortId} was not found in any of the ${resolved.searchedProjectCount} ` + `project(s) across ${resolved.searchedWorkspaceCount} workspace(s) this connection can access. ` + `Use harmony_list_projects to see them, or pass an explicit projectId.`);
       }
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client3.getCard(cardId);

package/dist/lib/api-client.js

@@ -1316,6 +1316,10 @@ class HarmonyApiClient {
   async getCardByShortId(projectId, shortId) {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
+  async resolveCardByShortId(shortId, preferredProjectId) {
+    const qs = preferredProjectId ? `?preferred_project_id=${encodeURIComponent(preferredProjectId)}` : "";
+    return this.request("GET", `/cards/resolve/${shortId}${qs}`);
+  }
   async bulkGetCards(projectId, shortIds) {
     return this.request("POST", `/projects/${projectId}/cards/bulk-get`, {
       shortIds

package/package.json

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

package/src/api-client.ts

@@ -164,6 +164,46 @@ export interface CardExternalLinkRow {
   created_at: string;
 }
 
+/** One candidate card returned by the cross-project short-id resolver (#709). */
+export interface ResolveCardCandidate {
+  cardId: string;
+  title: string;
+  projectId: string;
+  projectName: string | null;
+  workspaceId: string;
+  workspaceName: string | null;
+}
+
+/** Discriminated result of GET /cards/resolve/:shortId (#709). `found` carries
+ * the hydrated card + its project (for sticky-context + confirm-back);
+ * `ambiguous` carries the candidates so the caller asks which one; `not_found`
+ * carries the searched scope for a legible failure; `not_in_preferred` (#428)
+ * means a deliberately-set active project (the hard scope) doesn't hold the id,
+ * and carries the projects that DO so the caller can switch or pass an explicit
+ * projectId — the tool never silently hops to another project. */
+export type ResolveCardApiResult =
+  | {
+      kind: "found";
+      card: unknown;
+      project: {
+        id: string;
+        name: string | null;
+        workspaceId: string;
+        workspaceName: string | null;
+      };
+    }
+  | { kind: "ambiguous"; candidates: ResolveCardCandidate[] }
+  | {
+      kind: "not_found";
+      searchedWorkspaceCount: number;
+      searchedProjectCount: number;
+    }
+  | {
+      kind: "not_in_preferred";
+      preferredProjectId: string;
+      candidates: ResolveCardCandidate[];
+    };
+
 /** 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 {
@@ -694,6 +734,21 @@ export class HarmonyApiClient {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
 
+  // #709: resolve a `#shortId` across every project the caller can reach when no
+  // explicit project is in play (the remote/OAuth MCP seeds a workspace but no
+  // project). `preferredProjectId` biases to the session's active/sticky project
+  // so a deliberately-set context wins outright instead of reading as ambiguous.
+  // Always resolves (HTTP 200) with a discriminated body — the caller decides.
+  async resolveCardByShortId(
+    shortId: number,
+    preferredProjectId?: string | null,
+  ): Promise<ResolveCardApiResult> {
+    const qs = preferredProjectId
+      ? `?preferred_project_id=${encodeURIComponent(preferredProjectId)}`
+      : "";
+    return this.request("GET", `/cards/resolve/${shortId}${qs}`);
+  }
+
   async bulkGetCards(
     projectId: string,
     shortIds: number[],

package/src/server.ts

@@ -2872,9 +2872,113 @@ async function handleToolCall(
       }
       if (hasShortId) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId = (args.projectId as string) || getProjectId();
-        const result = await client.getCardByShortId(projectId, shortId);
-        return { success: true, ...result };
+        const explicitProjectId = args.projectId as string | undefined;
+
+        // Explicit projectId is the deterministic override: fetch from exactly
+        // that project and error if it's not there — never look elsewhere.
+        if (explicitProjectId) {
+          const result = await client.getCardByShortId(
+            explicitProjectId,
+            shortId,
+          );
+          return { success: true, ...result };
+        }
+
+        // No explicit project: resolve the `#shortId` (#709). The active/sticky
+        // project is a HARD SCOPE (#428) — when one is set, the resolver only
+        // matches within it (a miss comes back as `not_in_preferred`, handled
+        // below) and this read never repoints it. Cross-project auto-resolution
+        // + sticky happens ONLY when no active project is set — the remote/OAuth
+        // MCP case this feature exists for, where the session seeds a workspace
+        // but no project.
+        const activeProjectId = deps.getActiveProjectId();
+        const resolved = await client.resolveCardByShortId(
+          shortId,
+          activeProjectId,
+        );
+
+        if (resolved.kind === "found") {
+          const cardTitle =
+            (resolved.card as { title?: string } | null)?.title ??
+            `#${shortId}`;
+          const where = resolved.project.workspaceName
+            ? `project "${resolved.project.name ?? resolved.project.id}" (workspace "${resolved.project.workspaceName}")`
+            : `project "${resolved.project.name ?? resolved.project.id}"`;
+          // Sticky ONLY when this ESTABLISHES a context (none was set). A
+          // deliberately-set active project is a hard scope: `found` there means
+          // the card was already in it, so there is nothing to change — and we
+          // never let a read silently repoint a context the user chose (which,
+          // on the local stdio MCP, persists to ~/.harmony-mcp/config.json
+          // across sessions). Confirm the target back either way so a
+          // wrong-context resolve is visible immediately.
+          const established = activeProjectId == null;
+          if (established) {
+            deps.setActiveProject(resolved.project.id);
+          }
+          return {
+            success: true,
+            card: resolved.card,
+            resolvedProject: resolved.project,
+            activeProjectId: resolved.project.id,
+            note: established
+              ? `Resolved #${shortId} → "${cardTitle}" in ${where}. No active project was set — set to this for follow-up references.`
+              : `Resolved #${shortId} → "${cardTitle}" in ${where} (your active project).`,
+          };
+        }
+
+        if (resolved.kind === "not_in_preferred") {
+          // Hard scope (#428): the active project is a constraint the user set,
+          // so a `#shortId` that isn't in it is an error — NOT a silent hop to
+          // whatever other project happens to carry that number, and NOT a
+          // change to the active project. Name where it *does* live so the
+          // caller can switch context or fetch it explicitly.
+          const list = resolved.candidates
+            .map(
+              (c) =>
+                `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${
+                  c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""
+                } (projectId: ${c.projectId})`,
+            )
+            .join("\n");
+          throw new Error(
+            `#${shortId} is not in your active project (projectId: ${resolved.preferredProjectId}). ` +
+              `It exists in ${resolved.candidates.length} other project(s) you can access:\n${list}\n\n` +
+              `Switch with harmony_set_project_context, or pass an explicit projectId to fetch it directly.`,
+          );
+        }
+
+        if (resolved.kind === "ambiguous") {
+          // Never guess: hand the candidates back so the caller can disambiguate.
+          const list = resolved.candidates
+            .map(
+              (c) =>
+                `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${
+                  c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""
+                } (projectId: ${c.projectId})`,
+            )
+            .join("\n");
+          return {
+            success: true,
+            needsDisambiguation: true,
+            shortId,
+            candidates: resolved.candidates,
+            message:
+              `#${shortId} exists in ${resolved.candidates.length} projects you can access:\n${list}\n\n` +
+              `Ask which one is meant, then re-fetch with an explicit projectId ` +
+              `(or call harmony_set_project_context first).`,
+          };
+        }
+
+        // not_found — name the searched scope instead of the bare "No project
+        // specified", and point at the tools that list the caller's options.
+        throw new Error(
+          resolved.searchedProjectCount === 0
+            ? `#${shortId} can't be resolved: no project is accessible to this connection. ` +
+                `Check the workspace this connection is authorized for with harmony_list_workspaces.`
+            : `Card #${shortId} was not found in any of the ${resolved.searchedProjectCount} ` +
+                `project(s) across ${resolved.searchedWorkspaceCount} workspace(s) this connection can access. ` +
+                `Use harmony_list_projects to see them, or pass an explicit projectId.`,
+        );
       }
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client.getCard(cardId);