@codazen/harmonica-mcp 0.22.0 → 0.24.0

package/dist/index.js

@@ -22966,28 +22966,45 @@ function registerDropTools(server, ctx, client) {
   );
   server.tool(
     "get_drop",
-    "Get full details of a Drop by ID \u2014 state, member Revisions, target date, and audit trail.",
+    "Get full details of a Drop by ID \u2014 state, member Revisions, target date, and audit trail. Accepts either a UUID (drop-abc123) or a drop code (D-086). When passing a code, teamspaceId is required.",
     {
-      dropId: external_exports.string().describe("The Drop ID (UUID)")
+      dropId: external_exports.string().describe("The Drop ID (UUID, e.g. drop-abc123) or drop code (e.g. D-086). When passing a code, teamspaceId is required."),
+      teamspaceId: external_exports.string().optional().describe("Required when dropId is a drop code like D-086")
     },
-    async ({ dropId }) => {
-      const d = await client.getDrop(dropId);
-      if (!d) return { content: [{ type: "text", text: `Drop not found: ${dropId}` }], isError: true };
-      const lines = [
-        `ID: ${d.dropId}`,
-        `Code: ${d.dropCode}`,
-        `Name: ${d.name}`,
-        `Teamspace: ${d.teamspaceId}`,
-        `State: ${d.state}`,
-        d.description ? `Description: ${d.description}` : null,
-        d.targetDate ? `Target: ${d.targetDate}` : null,
-        d.releasedAt ? `Released: ${d.releasedAt}` : null,
-        d.rolledBackAt ? `Rolled back: ${d.rolledBackAt}` : null,
-        `Revisions (${d.revisionIds.length}): ${d.revisionIds.length === 0 ? "(none)" : d.revisionIds.join(", ")}`,
-        `Version: ${d.version}`,
-        `Created: ${d.createdAt}`
-      ].filter(Boolean);
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+    async ({ dropId, teamspaceId }) => {
+      try {
+        let resolvedId = dropId;
+        if (/^D-\d+$/i.test(dropId)) {
+          if (!teamspaceId) {
+            return { content: [{ type: "text", text: `teamspaceId is required when dropId is a drop code (e.g. D-086)` }], isError: true };
+          }
+          const normalizedCode = dropId.toUpperCase();
+          const drops = await client.listTeamspaceDrops(teamspaceId, void 0);
+          const match = drops.find((d2) => d2.dropCode.toUpperCase() === normalizedCode);
+          if (!match) return { content: [{ type: "text", text: `Drop not found: ${dropId}` }], isError: true };
+          resolvedId = match.dropId;
+        }
+        const d = await client.getDrop(resolvedId);
+        const notFoundMsg = resolvedId !== dropId ? `Drop not found: ${resolvedId} (code: ${dropId})` : `Drop not found: ${dropId}`;
+        if (!d) return { content: [{ type: "text", text: notFoundMsg }], isError: true };
+        const lines = [
+          `ID: ${d.dropId}`,
+          `Code: ${d.dropCode}`,
+          `Name: ${d.name}`,
+          `Teamspace: ${d.teamspaceId}`,
+          `State: ${d.state}`,
+          d.description ? `Description: ${d.description}` : null,
+          d.targetDate ? `Target: ${d.targetDate}` : null,
+          d.releasedAt ? `Released: ${d.releasedAt}` : null,
+          d.rolledBackAt ? `Rolled back: ${d.rolledBackAt}` : null,
+          `Revisions (${d.revisionIds.length}): ${d.revisionIds.length === 0 ? "(none)" : d.revisionIds.join(", ")}`,
+          `Version: ${d.version}`,
+          `Created: ${d.createdAt}`
+        ].filter(Boolean);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Failed to get drop: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+      }
     }
   );
   server.tool(
@@ -24398,7 +24415,7 @@ function registerPlanQualityTools(server, ctx, client) {
     "check_plan_quality",
     "Enqueue a Revision plan quality check across 6 dimensions (Scoped, Directional, Testable, Traceable, Assignable, Risk-aware). By default returns a taskId immediately (fire-and-forget) \u2014 use get_task_status or list_checks to retrieve results. Set wait=true to block until the check completes and receive the scorecard inline.",
     {
-      revisionId: external_exports.string().describe("The revision ID (e.g., rev-abc123)"),
+      revisionId: external_exports.string().describe("The revision or Beat Version ID (e.g., rev-abc123 or bv-abc123)"),
       projectId: external_exports.string().describe("The project ID"),
       wait: external_exports.boolean().optional().describe("If true, block until the check completes and return the scorecard inline. Default: false (returns taskId immediately).")
     },
@@ -24679,24 +24696,35 @@ function registerRevisionLifecycleTools(server, ctx, client) {
       title: external_exports.string().describe("Title for this revision"),
       description: external_exports.string().describe("What this revision delivers"),
       changeSummary: external_exports.string().describe("Brief summary of the change"),
+      beatVersionId: external_exports.string().min(1).optional().describe("Optional Beat Version ID to associate this revision with"),
       tags: external_exports.array(external_exports.string()).optional().describe("Tags for categorization"),
       priority: external_exports.coerce.number().optional().describe("Priority (lower = higher priority)"),
       estimatedEffort: external_exports.string().optional().describe("Estimated effort (e.g., S, M, L, XL)"),
       humanAssignee: humanAssigneeSchema.optional().describe('Human assignee (e.g. { email: "mmerchant@codazen.com", name: "Mike Merchant" })'),
       agentAssignee: agentAssigneeSchema.optional().describe('Agent assignee (e.g. { agentId: "maya", name: "Maya" })')
     },
-    async ({ beatId, title, description, changeSummary, tags, priority, estimatedEffort, humanAssignee, agentAssignee }) => {
+    async ({ beatId, title, description, changeSummary, beatVersionId, tags, priority, estimatedEffort, humanAssignee, agentAssignee }) => {
       try {
         await assertBeatInOrg(client, beatId, ctx.orgId);
         const beat = await client.getBeat(beatId);
         if (!beat) {
           return { content: [{ type: "text", text: `Beat not found: "${beatId}"` }], isError: true };
         }
+        if (beatVersionId !== void 0) {
+          const bv = await client.getBeatVersion(beatVersionId);
+          if (!bv) {
+            return { content: [{ type: "text", text: `Beat Version not found: "${beatVersionId}"` }], isError: true };
+          }
+          if (bv.beatId !== beatId || bv.projectId !== beat.projectId) {
+            return { content: [{ type: "text", text: `Beat Version "${beatVersionId}" belongs to a different Beat.` }], isError: true };
+          }
+        }
         const { revision, warnings } = await client.createRevision(beat.projectId, beatId, {
           title,
           description,
           changeSummary,
           changeImportance: "moderate",
+          beatVersionId,
           tags,
           priority,
           estimatedEffort,
@@ -24733,23 +24761,34 @@ function registerRevisionLifecycleTools(server, ctx, client) {
       changeSummary: external_exports.string().describe("Why this change is being made (recorded in audit trail)"),
       title: external_exports.string().optional().describe("New title"),
       description: external_exports.string().optional().describe("New description (what this revision delivers)"),
+      beatVersionId: external_exports.string().min(1).nullable().optional().describe("Beat Version ID to associate \u2014 set null to clear"),
       tags: external_exports.array(external_exports.string()).optional().describe("Tags for categorization"),
       priority: external_exports.coerce.number().optional().describe("Priority (lower = higher priority)"),
       estimatedEffort: external_exports.string().optional().describe("Effort estimate (e.g., S, M, L, XL)"),
       humanAssignee: humanAssigneeSchema.nullable().optional().describe("Human assignee \u2014 set null to clear"),
       agentAssignee: agentAssigneeSchema.nullable().optional().describe("Agent assignee \u2014 set null to clear")
     },
-    async ({ revisionId, changeSummary, ...changes }) => {
+    async ({ revisionId, changeSummary, beatVersionId, ...changes }) => {
       try {
         const revision = await client.getRevision(revisionId);
         if (!revision) {
           return { content: [{ type: "text", text: `Revision not found: "${revisionId}"` }], isError: true };
         }
         await assertBeatInOrg(client, revision.beatId, ctx.orgId);
+        if (typeof beatVersionId === "string") {
+          const bv = await client.getBeatVersion(beatVersionId);
+          if (!bv) {
+            return { content: [{ type: "text", text: `Beat Version not found: "${beatVersionId}"` }], isError: true };
+          }
+          if (bv.beatId !== revision.beatId || bv.projectId !== revision.projectId) {
+            return { content: [{ type: "text", text: `Beat Version "${beatVersionId}" belongs to a different Beat.` }], isError: true };
+          }
+        }
         const updates = { changeSummary };
         for (const [k, v] of Object.entries(changes)) {
           if (v !== void 0) updates[k] = v;
         }
+        if (beatVersionId !== void 0) updates.beatVersionId = beatVersionId;
         if (Object.keys(updates).length <= 1) {
           return { content: [{ type: "text", text: "No fields provided to update." }], isError: true };
         }
@@ -24893,37 +24932,29 @@ function registerSnapshotTools(server, ctx, client) {
           isError: true
         };
       }
+      const trimmed = snapshotInput.trim();
+      const importOptions = { targetOrgId: ctx.orgId, targetUserId: ctx.user.userId };
+      if (trimmed.startsWith("https://")) {
+        if (isPrivateHost(trimmed)) {
+          throw new Error("Snapshot URL must point to a public host \u2014 private, link-local, and loopback addresses are not permitted.");
+        }
+        const result2 = await client.importProjectSnapshotFromUrl(trimmed, importOptions);
+        return { content: [{ type: "text", text: formatImportSummary(result2) }] };
+      }
+      if (trimmed.startsWith("http://")) {
+        throw new Error("Snapshot URL must use https:// \u2014 http:// is not permitted.");
+      }
       const snapshotJson = await resolveSnapshotInput(snapshotInput);
       let parsed;
       try {
         parsed = JSON.parse(snapshotJson);
       } catch {
-        const urlHint = snapshotInput.trim().startsWith("https://") ? ` fetched from ${snapshotInput.trim().split("?")[0]}` : "";
-        throw new Error(`Snapshot is not valid JSON${urlHint}. The URL may have returned an error page instead of snapshot data.`);
+        throw new Error("Snapshot is not valid JSON. The content may be corrupted.");
       }
-      assertSnapshotShape(parsed, snapshotInput.trim().startsWith("https://") ? ` fetched from ${snapshotInput.trim().split("?")[0]}` : "");
+      assertSnapshotShape(parsed, "");
       const normalized = normalizeSnapshot(parsed);
-      const result = await client.importProjectSnapshot(normalized, {
-        targetOrgId: ctx.orgId,
-        targetUserId: ctx.user.userId
-      });
-      const summary = [
-        `Imported project: ${result.projectId}`,
-        `  Beats: ${result.counts.beats}`,
-        `  Proposals: ${result.counts.proposals}`,
-        `  Revisions: ${result.counts.revisions}`,
-        `  Activities: ${result.counts.activities}`,
-        `  Questions: ${result.counts.questions}`,
-        `  Notes: ${result.counts.notes}`,
-        `  Tasks: ${result.counts.tasks}`,
-        `  Submissions: ${result.counts.submissions}`,
-        `  PromptLogs: ${result.counts.promptLogs}`
-      ];
-      if (result.errors.length > 0) {
-        summary.push("", `Errors (${result.errors.length}):`);
-        result.errors.forEach((e) => summary.push(`  - ${e}`));
-      }
-      return { content: [{ type: "text", text: summary.join("\n") }] };
+      const result = await client.importProjectSnapshot(normalized, importOptions);
+      return { content: [{ type: "text", text: formatImportSummary(result) }] };
     }
   );
 }
@@ -24952,27 +24983,30 @@ function normalizeSnapshot(raw) {
 }
 async function resolveSnapshotInput(input) {
   const trimmed = input.trim();
-  if (trimmed.startsWith("https://")) {
-    if (isPrivateHost(trimmed)) {
-      throw new Error("Snapshot URL must point to a public host \u2014 private, link-local, and loopback addresses are not permitted.");
-    }
-    let res;
-    try {
-      res = await fetch(trimmed, { redirect: "error", signal: AbortSignal.timeout(3e4) });
-    } catch (err) {
-      throw new Error(`Failed to fetch snapshot URL: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    if (!res.ok) throw new Error(`Failed to fetch snapshot from URL: ${res.status}`);
-    return res.text();
-  }
-  if (trimmed.startsWith("http://")) {
-    throw new Error("Snapshot URL must use https:// \u2014 http:// is not permitted.");
-  }
   if (trimmed.startsWith("/") || trimmed.startsWith("~")) {
     return (0, import_promises.readFile)(trimmed, "utf-8");
   }
   return trimmed;
 }
+function formatImportSummary(result) {
+  const lines = [
+    `Imported project: ${result.projectId}`,
+    `  Beats: ${result.counts.beats}`,
+    `  Proposals: ${result.counts.proposals}`,
+    `  Revisions: ${result.counts.revisions}`,
+    `  Activities: ${result.counts.activities}`,
+    `  Questions: ${result.counts.questions}`,
+    `  Notes: ${result.counts.notes}`,
+    `  Tasks: ${result.counts.tasks}`,
+    `  Submissions: ${result.counts.submissions}`,
+    `  PromptLogs: ${result.counts.promptLogs}`
+  ];
+  if (result.errors.length > 0) {
+    lines.push("", `Errors (${result.errors.length}):`);
+    result.errors.forEach((e) => lines.push(`  - ${e}`));
+  }
+  return lines.join("\n");
+}
 function isPrivateHost(url) {
   let hostname2;
   try {
@@ -26401,6 +26435,7 @@ function createHttpClient(config2) {
       return download;
     },
     importProjectSnapshot: (snapshot, options) => request("POST", "/api/projects/import", { ...snapshot, importOptions: options }, LONG_RUNNING_TIMEOUT_MS),
+    importProjectSnapshotFromUrl: (url2, options) => request("POST", "/api/projects/import", { snapshotUrl: url2, importOptions: options }, LONG_RUNNING_TIMEOUT_MS),
     // Embedding similarity
     embedProjectEntities: (projectId) => request("POST", `/api/projects/${encodeURIComponent(projectId)}/embeddings/generate`),
     findSimilarNotes: async (noteId, projectId, options) => {
@@ -26708,7 +26743,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"0.22.0"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"0.24.0"} starting\u2026`);
   const config2 = loadConfig();
   const client = createHttpClient({
     apiBaseUrl: config2.apiBaseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codazen/harmonica-mcp",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "MCP server for Harmonica — connect Claude to your Harmonica projects",
   "license": "MIT",
   "bin": {