@codazen/harmonica-mcp 4.4.0 → 4.4.2

package/dist/index.js

@@ -21913,7 +21913,7 @@ function registerActivityTools(server, ctx, client) {
         minImportance: importance
       });
       if (entries.length === 0) {
-        return { content: [{ type: "text", text: "No activities found for this project." }] };
+        return { content: [{ type: "text", text: "No activities found for this system." }] };
       }
       const lines = [
         `# Project Activities (${entries.length}${hasMore ? "+" : ""})`,
@@ -22416,6 +22416,54 @@ var CHECK_MAX_SCORES = {
   root_coda_quality: 5
 };
 
+// ../../libs/harmonica-services/src/mcp/errors.ts
+var BeatQualityGateError = class extends Error {
+  code = "beat_quality_gate_failed";
+  failure;
+  constructor(failure) {
+    super(failure.message);
+    this.failure = failure;
+  }
+};
+var PlanVersionsIdempotencyError = class extends Error {
+  code = "plan_versions_already_exist";
+  existingBeatVersionIds;
+  constructor(existingBeatVersionIds) {
+    super(
+      `Beat already has ${existingBeatVersionIds.length} planned Beat Version(s). Pass force=true to plan again.`
+    );
+    this.existingBeatVersionIds = existingBeatVersionIds;
+  }
+};
+function isRenderableGateFailure(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const f = value;
+  return typeof f.reason === "string" && typeof f.message === "string";
+}
+var CheckResultPendingError = class extends Error {
+  code = "check_result_pending";
+  taskId;
+  constructor(taskId) {
+    super(`Task ${taskId} completed but its scorecard is not yet readable on the blocking path.`);
+    this.name = "CheckResultPendingError";
+    this.taskId = taskId;
+  }
+};
+function renderCheckResultPending(err, alsoTry = ["list_checks"]) {
+  const paths = [`get_job_status (jobId="${err.taskId}")`, ...alsoTry].join(" or ");
+  return {
+    content: [{
+      type: "text",
+      text: [
+        `**Status:** completed \u2014 scorecard not yet readable on the blocking path`,
+        `**Job ID:** ${err.taskId}`,
+        "",
+        `The check succeeded on the async path. Retrieve the scorecard with ${paths}.`
+      ].join("\n")
+    }]
+  };
+}
+
 // ../../libs/harmonica-services/src/mcp/tools/beat-quality-tools.ts
 var POLL_INTERVAL_MS = 4e3;
 var POLL_TIMEOUT_MS = 18e4;
@@ -22438,7 +22486,7 @@ async function pollForCheck(client, taskId) {
     consecutiveErrors = 0;
     if (!task) throw new Error(`Task ${taskId} not found`);
     if (task.status === "completed") {
-      if (!task.result) throw new Error(`async:completed:no-result Task ${taskId} succeeded on the async path but the scorecard is not yet readable on the blocking path \u2014 use list_checks or get_job_status to retrieve it.`);
+      if (!task.result) throw new CheckResultPendingError(taskId);
       return task.result;
     }
     if (task.status === "failed") throw new Error(`Quality check failed: ${task.error ?? "unknown error"}`);
@@ -22486,6 +22534,7 @@ Use get_job_status with jobId="${taskId}" to poll for results, or list_checks to
       const check2 = await pollForCheck(client, taskId);
       return { content: [{ type: "text", text: formatScorecard(check2) }] };
     } catch (err) {
+      if (err instanceof CheckResultPendingError) return renderCheckResultPending(err);
       const message = err instanceof Error ? err.message : String(err);
       return { content: [{ type: "text", text: `Quality check failed: ${message}` }], isError: true };
     }
@@ -23094,7 +23143,7 @@ function registerBeatTools(server, ctx, client) {
       beatId: external_exports.string().optional().describe("Override beat ID (auto-generated if omitted)"),
       humanAssignee: humanAssigneeSchema.optional().describe('Human assignee (e.g. { email: "lwu@codazen.com", name: "Liam Wu" })'),
       agentAssignee: agentAssigneeSchema.optional().describe('Agent assignee (e.g. { agentId: "maya", name: "Maya" })'),
-      branch: external_exports.string().optional().describe('Git branch for code assessment (falls back to Project.repoDefaultBranch \u2192 "main")')
+      branch: external_exports.string().optional().describe('Git branch for code assessment (falls back to System.repoDefaultBranch \u2192 "main")')
     },
     async ({ systemId, title, description, tags, priority, estimatedEffort, beatId, humanAssignee, agentAssignee, branch }) => {
       try {
@@ -23302,31 +23351,6 @@ var BeatVersionRelocateError = class extends Error {
 var REVISION_STATUSES = ["active", "archived"];
 var BEAT_VERSION_STATUSES = ["active", "archived"];
 
-// ../../libs/harmonica-services/src/mcp/errors.ts
-var BeatQualityGateError = class extends Error {
-  code = "beat_quality_gate_failed";
-  failure;
-  constructor(failure) {
-    super(failure.message);
-    this.failure = failure;
-  }
-};
-var PlanVersionsIdempotencyError = class extends Error {
-  code = "plan_versions_already_exist";
-  existingBeatVersionIds;
-  constructor(existingBeatVersionIds) {
-    super(
-      `Beat already has ${existingBeatVersionIds.length} planned Beat Version(s). Pass force=true to plan again.`
-    );
-    this.existingBeatVersionIds = existingBeatVersionIds;
-  }
-};
-function isRenderableGateFailure(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const f = value;
-  return typeof f.reason === "string" && typeof f.message === "string";
-}
-
 // ../../libs/harmonica-services/src/mcp/tools/beat-version-tools.ts
 function registerBeatVersionTools(server, ctx, client) {
   server.tool(
@@ -24150,7 +24174,7 @@ ${g.acceptanceCriteria}` : null,
     deliverables: external_exports.string().max(2e4).optional().describe("The Track's deliverables as Markdown bullet points (parallel to acceptanceCriteria)"),
     acceptanceCriteria: external_exports.string().max(2e4).optional().describe("The Track's acceptance criteria (Markdown), parallel to its deliverables"),
     vuRate: external_exports.number().nonnegative().describe("Value-Unit rate (billing rate for this engagement)"),
-    systemId: external_exports.string().optional().describe("Optional project to scope this Track to"),
+    systemId: external_exports.string().optional().describe("Optional System to scope this Track to"),
     movementId: external_exports.string().optional().describe("Optional Movement (client SOW) to scope this Track to"),
     parentGroupId: external_exports.string().optional().describe("Optional parent Track ID for nested grouping (Phase 0 scaffolding)")
   };
@@ -24464,7 +24488,7 @@ async function pollForCheck2(client, taskId) {
     consecutiveErrors = 0;
     if (!task) throw new Error(`Task ${taskId} not found`);
     if (task.status === "completed") {
-      if (!task.result) throw new Error(`Task ${taskId} completed with no result`);
+      if (!task.result) throw new CheckResultPendingError(taskId);
       return task.result;
     }
     if (task.status === "failed") throw new Error(`Drop quality check failed: ${task.error ?? "unknown error"}`);
@@ -24520,7 +24544,7 @@ function registerDropQualityTools(server, ctx, client) {
                 `Drop quality check enqueued for ${dropId}.`,
                 `Task ID: ${taskId}`,
                 "",
-                `Use get_job_status with jobId="${taskId}" to poll, or list_checks with checkType="drop_quality" to view results.`
+                `Use get_job_status with jobId="${taskId}" to view results \u2014 list_checks has no dropId filter.`
               ].join("\n")
             }]
           };
@@ -24528,6 +24552,7 @@ function registerDropQualityTools(server, ctx, client) {
         const check2 = await pollForCheck2(client, taskId);
         return { content: [{ type: "text", text: formatReport(check2) }] };
       } catch (err) {
+        if (err instanceof CheckResultPendingError) return renderCheckResultPending(err, []);
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text", text: `Drop quality check failed: ${message}` }], isError: true };
       }
@@ -24914,8 +24939,8 @@ function registerEmbeddingTools(server, ctx, client) {
     "search",
     "Free-text semantic search across system, teamspace, or org scope. Provide exactly one of systemId / teamspaceId / orgId. Teamspace and org searches fan out across child projects and merge by score. Cross-project results carry the source project name.",
     {
-      systemId: external_exports.string().optional().describe("Search within a single project"),
-      teamspaceId: external_exports.string().optional().describe("Search across all projects in a teamspace"),
+      systemId: external_exports.string().optional().describe("Search within a single System"),
+      teamspaceId: external_exports.string().optional().describe("Search across all Systems in a teamspace"),
       orgId: external_exports.string().optional().describe("Search across every system in this organization \u2014 see list_organizations"),
       query: external_exports.string().describe("Natural language search query"),
       limit: external_exports.coerce.number().int().min(1).max(50).optional().default(10).describe("Max results to return. Default 10"),
@@ -27464,7 +27489,7 @@ function registerNoteTools(server, ctx, client) {
     {
       systemId: external_exports.string().describe("The system ID"),
       beatId: external_exports.string().optional().describe("Scope to a specific beat (omit for all system notes)"),
-      noteType: external_exports.union([external_exports.enum(NOTE_TYPE_VALUES), external_exports.array(external_exports.enum(NOTE_TYPE_VALUES)).min(1)]).optional().describe('Filter by note type \u2014 single value or array for multi-select (e.g. ["constraint", "assumption"])'),
+      noteType: external_exports.union([external_exports.enum(NOTE_TYPE_VALUES), external_exports.array(external_exports.enum(NOTE_TYPE_VALUES)).min(1)]).optional().describe('Filter by note type \u2014 single value or array for multi-select (e.g. ["constraint", "guidance"])'),
       status: external_exports.enum(NOTE_STATUS_VALUES).optional().describe("Filter by status"),
       revisionId: external_exports.string().optional().describe("Filter to notes scoped to a specific revision"),
       beatVersionId: external_exports.string().optional().describe("Filter to notes scoped to a specific Beat Version (planning increment)"),
@@ -27632,12 +27657,12 @@ function registerNoteTools(server, ctx, client) {
     },
     async ({ systemId }) => {
       await assertSystemExists(client, systemId);
-      const DOCUMENT_FETCH_LIMIT = 5e3;
-      const { notes: docs, hasMore: truncated } = await client.listAllSystemNotes(systemId, { noteType: "document" }, DOCUMENT_FETCH_LIMIT);
+      const { notes: docs, hasMore } = await client.listAllSystemNotes(systemId, { noteType: "document" });
       const visibleDocs = docs.filter((d) => d.status !== DISMISSED_NOTE_STATUS);
-      const truncationNotice = truncated && visibleDocs.length > 0 ? "\n\n> \u26A0\uFE0F This system has more than 5000 documents. Some documents may not be shown.\n" : "";
-      const text = formatDocumentList(visibleDocs) + truncationNotice;
-      return { content: [{ type: "text", text }] };
+      if (hasMore) {
+        return { content: [{ type: "text", text: `Unexpected: listAllSystemNotes returned hasMore=true on the no-limit path for system ${systemId} \u2014 the document list may be incomplete. This is a server-side regression.` }], isError: true };
+      }
+      return { content: [{ type: "text", text: formatDocumentList(visibleDocs) }] };
     }
   );
   server.tool(
@@ -27780,7 +27805,7 @@ ${text}` }] };
       systemId: external_exports.string().optional().describe("The system ID (for access control). Provide systemId or orgId, not both."),
       orgId: external_exports.string().optional().describe("The org ID (for org-level notes). Provide orgId or systemId, not both."),
       noteId: external_exports.string().describe("The note ID to update"),
-      noteType: external_exports.enum(NOTE_TYPE_VALUES).optional().describe("Reclassify the note type (e.g. assumption \u2192 guidance)"),
+      noteType: external_exports.enum(NOTE_TYPE_VALUES).optional().describe("Reclassify the note type (e.g. context \u2192 guidance)"),
       status: external_exports.enum(NOTE_STATUS_VALUES).optional().describe("New status"),
       content: external_exports.string().optional().describe("Updated content"),
       rationale: external_exports.string().optional().describe("Why this note exists or why this decision was made"),
@@ -28226,7 +28251,7 @@ ${formatTree(tree.root)}` }] };
       heading: external_exports.string().min(1).max(200).describe('Section label, e.g. "Decision Log"'),
       parentNoteId: external_exports.string().optional().describe("Parent page's Note ID; defaults to the notebook root"),
       noteType: external_exports.enum(["context", "constraint", "guidance", "decision", "document"]).optional().describe("Note type to collect (default: decision)"),
-      systemId: external_exports.string().optional().describe("Project scope; if omitted, the Notebook's first bound project scope is used"),
+      systemId: external_exports.string().optional().describe("System scope; if omitted, the Notebook's first bound system scope is used"),
       limit: external_exports.number().int().min(1).max(500).optional().describe("Max members to show (default: 25)"),
       order: external_exports.enum(["newest", "oldest"]).optional().describe("Sort order (default: newest)"),
       significance: external_exports.enum(["strategic", "structural", "implementation"]).optional().describe("Only for decision notes \u2014 filter to a significance tier (e.g. strategic). Omit to include all.")
@@ -28244,15 +28269,15 @@ ${formatTree(tree.root)}` }] };
           isError: true
         };
       }
-      let scopeProjectId = systemId;
-      if (!scopeProjectId) {
+      let scopeSystemId = systemId;
+      if (!scopeSystemId) {
         try {
           const bindings = await client.getNotebookScopeBindings(notebookId);
-          scopeProjectId = bindings?.find((b) => b.scopeType === "system" || b.scopeType === "project")?.scopeId;
+          scopeSystemId = bindings?.find((b) => b.scopeType === "system" || b.scopeType === "project")?.scopeId;
         } catch {
         }
       }
-      if (!scopeProjectId) {
+      if (!scopeSystemId) {
         return { content: [{ type: "text", text: "No system scope: pass systemId or bind the notebook to a system first." }], isError: true };
       }
       let tree;
@@ -28282,7 +28307,7 @@ ${formatTree(tree.root)}` }] };
           parentId: placement.parentNoteId,
           query: {
             source: "notes",
-            scope: `project:${scopeProjectId}`,
+            scope: `system:${scopeSystemId}`,
             noteType: noteType ?? "decision",
             limit: limit ?? 25,
             sortBy: order === "oldest" ? "createdAt_asc" : "createdAt_desc",
@@ -28301,7 +28326,7 @@ ${formatTree(tree.root)}` }] };
         return { content: [{ type: "text", text: `Failed to add collection: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
       }
       return {
-        content: [{ type: "text", text: `Live collection added: **${heading}** (${noteType ?? "decision"} @ project:${scopeProjectId}) under ${placement.parentNoteId} at depth ${placement.childDepth}, position ${position}.` }]
+        content: [{ type: "text", text: `Live collection added: **${heading}** (${noteType ?? "decision"} @ system:${scopeSystemId}) under ${placement.parentNoteId} at depth ${placement.childDepth}, position ${position}.` }]
       };
     }
   );
@@ -28314,7 +28339,7 @@ ${formatTree(tree.root)}` }] };
       parentNoteId: external_exports.string().optional().describe("The page Note ID the section sits under; defaults to the notebook root"),
       heading: external_exports.string().min(1).max(200).optional().describe("New section label"),
       noteType: external_exports.enum(["context", "constraint", "guidance", "decision", "document"]).optional().describe("New note type to collect"),
-      systemId: external_exports.string().optional().describe("New project scope"),
+      systemId: external_exports.string().optional().describe("New system scope"),
       limit: external_exports.number().int().min(1).max(500).optional().describe("New max members to show"),
       order: external_exports.enum(["newest", "oldest"]).optional().describe("New sort order"),
       significance: external_exports.enum(["strategic", "structural", "implementation"]).optional().describe("New significance-tier filter (decision notes only)")
@@ -28356,9 +28381,14 @@ ${formatTree(tree.root)}` }] };
         return { content: [{ type: "text", text: `Element "${elementId}" is not a live collection \u2014 its configuration cannot be edited here.` }], isError: true };
       }
       const base = existing.query;
+      const normalizedScope = systemId ? `system:${systemId}` : base.scope.replace(/^project:/, "system:");
+      const colonIdx = normalizedScope.indexOf(":");
+      if (colonIdx <= 0 || colonIdx === normalizedScope.length - 1) {
+        return { content: [{ type: "text", text: `Stored scope '${base.scope}' has no system id \u2014 pass an explicit systemId to re-bind this collection.` }], isError: true };
+      }
       const mergedQuery = {
         source: "notes",
-        scope: systemId !== void 0 ? `project:${systemId}` : base.scope,
+        scope: normalizedScope,
         noteType: noteType ?? base.noteType,
         limit: limit ?? base.limit,
         sortBy: order !== void 0 ? order === "oldest" ? "createdAt_asc" : "createdAt_desc" : base.sortBy,
@@ -28933,7 +28963,7 @@ async function pollForRootCodaCheck(client, taskId) {
     consecutiveErrors = 0;
     if (!task) throw new Error(`Task ${taskId} not found`);
     if (task.status === "completed") {
-      if (!task.result) throw new Error(`Task ${taskId} completed with no result`);
+      if (!task.result) throw new CheckResultPendingError(taskId);
       const result = task.result;
       if (!Array.isArray(result.dimensions) || typeof result.overallScore !== "number") {
         throw new Error(`Task ${taskId} did not return a root Coda scorecard \u2014 was it a run_check task?`);
@@ -29138,7 +29168,7 @@ function registerOrganizationTools(server, ctx, client) {
                 `Root Coda quality check enqueued for ${orgId}.`,
                 `Task ID: ${taskId}`,
                 "",
-                `Use get_job_status with jobId="${taskId}" to poll, or list_checks with checkType="root_coda_quality" to view results.`
+                `Use get_job_status with jobId="${taskId}" to view results \u2014 org-scoped checks are not listed by list_checks.`
               ].join("\n")
             }]
           };
@@ -29146,6 +29176,7 @@ function registerOrganizationTools(server, ctx, client) {
         const check2 = await pollForRootCodaCheck(client, taskId);
         return { content: [{ type: "text", text: formatRootCodaReport(check2) }] };
       } catch (err) {
+        if (err instanceof CheckResultPendingError) return renderCheckResultPending(err, []);
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text", text: `Root Coda quality check failed: ${message}` }], isError: true };
       }
@@ -29181,7 +29212,7 @@ async function pollForCheck3(client, taskId) {
     }
     consecutiveErrors = 0;
     if (task.status === "completed") {
-      if (!task.result) throw new Error(`async:completed:no-result Task ${taskId} succeeded on the async path but the scorecard is not yet readable on the blocking path \u2014 use list_checks or get_job_status to retrieve it.`);
+      if (!task.result) throw new CheckResultPendingError(taskId);
       return task.result;
     }
     if (task.status === "failed") throw new Error(`Beat version quality check failed: ${task.error ?? "unknown error"}`);
@@ -29242,6 +29273,7 @@ Use get_job_status with jobId="${task.taskId}" to poll for results, or list_chec
       const check2 = await pollForCheck3(client, task.taskId);
       return { content: [{ type: "text", text: formatScorecard2(check2) }] };
     } catch (err) {
+      if (err instanceof CheckResultPendingError) return renderCheckResultPending(err);
       const message = err instanceof Error ? err.message : String(err);
       return { content: [{ type: "text", text: `Beat version quality check failed: ${message}` }], isError: true };
     }
@@ -29286,7 +29318,7 @@ async function pollForCheck4(client, taskId) {
     consecutiveErrors = 0;
     if (!task) throw new Error(`Task ${taskId} not found`);
     if (task.status === "completed") {
-      if (!task.result) throw new Error(`Task ${taskId} completed with no result`);
+      if (!task.result) throw new CheckResultPendingError(taskId);
       return task.result;
     }
     if (task.status === "failed") throw new Error(`Portfolio coherence check failed: ${task.error ?? "unknown error"}`);
@@ -29390,6 +29422,7 @@ function registerPortfolioCoherenceTools(server, ctx, client) {
         const check2 = await pollForCheck4(client, taskId);
         return { content: [{ type: "text", text: formatReport2(check2) }] };
       } catch (err) {
+        if (err instanceof CheckResultPendingError) return renderCheckResultPending(err);
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text", text: `Portfolio coherence check failed: ${message}` }], isError: true };
       }
@@ -30149,7 +30182,7 @@ async function pollForCheck5(client, taskId) {
     }
     consecutiveErrors = 0;
     if (task.status === "completed") {
-      if (!task.result) throw new Error(`Task ${taskId} completed with no result`);
+      if (!task.result) throw new CheckResultPendingError(taskId);
       return task.result;
     }
     if (task.status === "failed") throw new Error(`Revision quality check failed: ${task.error ?? "unknown error"}`);
@@ -30211,6 +30244,7 @@ Use get_job_status with jobId="${task.taskId}" to poll for results, or list_chec
         const check2 = await pollForCheck5(client, task.taskId);
         return { content: [{ type: "text", text: formatScorecard3(check2) }] };
       } catch (err) {
+        if (err instanceof CheckResultPendingError) return renderCheckResultPending(err);
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text", text: `Revision quality check failed: ${message}` }], isError: true };
       }
@@ -34218,7 +34252,7 @@ function createHttpClient(config2) {
     },
     listSystemDeliverableGroups: async (systemId) => {
       const res = await request("GET", `/api/systems/${encodeURIComponent(systemId)}/deliverable-groups`);
-      if (res === void 0) throw new Error(`Project ${systemId} not found`);
+      if (res === void 0) throw new Error(`System ${systemId} not found`);
       return res.deliverableGroups;
     },
     listMovementDeliverableGroups: async (movementId) => {
@@ -34798,7 +34832,7 @@ function createHttpClient(config2) {
         `/api/systems/${encodeURIComponent(systemId)}/beats/draft`,
         input
       );
-      if (!result) throw new Error(`Beat draft failed: project ${systemId} not found`);
+      if (!result) throw new Error(`Beat draft failed: system ${systemId} not found`);
       return result;
     },
     triggerSystemEmbedding: async (systemId) => {
@@ -35064,7 +35098,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"4.4.0"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"4.4.2"} starting\u2026`);
   const config2 = loadConfig();
   const client = createHttpClient({
     apiBaseUrl: config2.apiBaseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codazen/harmonica-mcp",
-  "version": "4.4.0",
+  "version": "4.4.2",
   "description": "MCP server for Harmonica — connect any MCP-compatible AI assistant to Harmonica",
   "license": "MIT",
   "bin": {