@codazen/harmonica-mcp 0.31.0 → 1.0.0

package/dist/index.js

@@ -25360,6 +25360,63 @@ function registerRevisionLifecycleTools(server, ctx, client) {
       }
     }
   );
+  server.tool(
+    "create_pr_for_revision",
+    "Open a Harmonica-initiated DRAFT pull request for a revision and link it back via revision.scm. Cuts a branch (agent/rev-<short>-<slug>), bootstraps it with an empty commit, opens a draft PR whose body starts with the `Harmonica: rev-<uuid>` marker, then records the PR on the revision. Rejects if the revision already has a linked PR, or if the project has no repo configured. Dry-run by default \u2014 call with `confirm: true` to actually create the branch and PR. Leaves the revision in `draft`; transition it to `open` when the PR is marked ready for review.",
+    {
+      revisionId: external_exports.string().describe("The revision ID (e.g., rev-abc123)"),
+      confirm: external_exports.boolean().optional().describe("Set true to create the branch + draft PR. Omitted/false performs a dry-run that only describes what would happen \u2014 no GitHub or DB writes.")
+    },
+    async ({ revisionId, confirm }) => {
+      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 (!confirm) {
+          const shortId = revisionId.split("-").slice(0, 2).join("-");
+          const lines2 = [
+            "**Dry run** \u2014 no PR created. Re-run with `confirm: true` to proceed.",
+            "",
+            `**Revision:** ${revisionId}`,
+            `**Title:** ${revision.title}`
+          ];
+          if (revision.scm) {
+            lines2.push("", `\u26A0 This revision already has a linked PR (#${revision.scm.number} \u2014 ${revision.scm.url}). create_pr_for_revision would be rejected.`);
+          } else {
+            const project = await client.getProject(revision.projectId);
+            if (!project?.repoOwner || !project?.repoName || !project?.repoDefaultBranch) {
+              lines2.push("", "\u26A0 The project has no repo configured (repoOwner/repoName/repoDefaultBranch). create_pr_for_revision would be rejected.");
+            } else {
+              lines2.push(
+                "",
+                `Would open a draft PR against \`${project.repoOwner}/${project.repoName}:${project.repoDefaultBranch}\` on a new \`agent/${shortId}-\u2026\` branch, with body starting \`Harmonica: ${revisionId}\`.`
+              );
+            }
+          }
+          return { content: [{ type: "text", text: lines2.join("\n") }] };
+        }
+        const result = await client.createPrForRevision(revisionId);
+        if (!result.success) {
+          return { content: [{ type: "text", text: `Failed to create PR (${result.error.code}): ${result.error.message}` }], isError: true };
+        }
+        const lines = [
+          "Draft PR created and linked to the revision.",
+          "",
+          `**Revision:** ${result.result.revisionId}`,
+          `**PR:** #${result.result.prNumber} \u2014 ${result.result.prUrl}`,
+          `**Branch:** ${result.result.branch}`,
+          "",
+          "The revision stays in `draft`. Transition it to `open` once the PR is marked ready for review."
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Failed to create PR for revision: ${message}` }], isError: true };
+      }
+    }
+  );
 }
 
 // ../../libs/harmonica-services/src/mcp/tools/session-tools.ts
@@ -26229,16 +26286,16 @@ ${JSON.stringify(task.result, null, 2)}
     }
   );
   server.tool(
-    "implement_revision",
-    "Trigger an agent session to implement a Revision. The agent reads the Revision spec and beat-level Notes, writes code, commits, pushes a branch named agent/rev-{id}-{title}, and creates a draft PR with the Revision ID pre-populated in the PR body. Returns a job ID \u2014 use get_job_status to track progress. Requires agentCapabilities.implementation enabled on the project.",
+    "start_session",
+    'Start an agent session from a free-form message \u2014 like opening a Claude Code conversation pointed at your project. The message is the only instruction: describe what you want ("investigate why login fails", "implement revision rev-abc123", "what does the auth flow do?") and the agent resolves any entity references itself and does whatever the work needs \u2014 investigate and report findings, or change code and open a PR. A findings-only result with no PR is a valid outcome. Returns a job ID \u2014 use get_job_status to track progress. Requires agent sessions enabled on the project.',
     {
-      revisionId: external_exports.string().min(1).describe("The Revision ID to implement (e.g., rev-abc123)"),
-      projectId: external_exports.string().min(1).describe("The project ID")
+      projectId: external_exports.string().min(1).describe("The project ID \u2014 the trusted scope the session is rooted at"),
+      message: external_exports.string().min(1).describe("Free-form first message describing what the session should do")
     },
-    async ({ revisionId, projectId }) => {
+    async ({ projectId, message }) => {
       try {
         await assertProjectInOrg(client, projectId, ctx.orgId);
-        const task = await client.implementRevision(revisionId, projectId, {
+        const task = await client.startSession(projectId, message, {
           name: ctx.user.name,
           email: ctx.user.email
         });
@@ -26246,20 +26303,20 @@ ${JSON.stringify(task.result, null, 2)}
           content: [{
             type: "text",
             text: [
-              "Revision implementation session queued.",
+              "Agent session queued.",
               "",
-              `**Revision:** ${revisionId}`,
+              `**Project:** ${projectId}`,
               `**Task ID:** ${task.taskId}`,
               `**Status:** ${task.status}`,
               "",
-              "The agent will read the Revision spec and beat-level Notes, implement the code, and create a draft PR.",
-              "Use `get_job_status` with the job ID to check progress and see the result (branch, PR URL, tool count, duration)."
+              "The agent runs as a single thread: it resolves any entity references in your message and produces whatever the work needs \u2014 findings, file changes, and/or a PR.",
+              "Use `get_job_status` with the job ID to check progress and see what it produced."
             ].join("\n")
           }]
         };
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: "text", text: `Failed to start revision implementation: ${message}` }], isError: true };
+        const errMessage = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Failed to start session: ${errMessage}` }], isError: true };
       }
     }
   );
@@ -26582,9 +26639,10 @@ function createHttpClient(config2) {
   }
   const DEFAULT_TIMEOUT_MS = parseInt(process.env.MCP_HTTP_TIMEOUT_MS || "30000", 10);
   const LONG_RUNNING_TIMEOUT_MS = parseInt(process.env.MCP_HTTP_LONG_TIMEOUT_MS || "180000", 10);
+  const getApiKey = () => typeof config2.apiKey === "function" ? config2.apiKey() : config2.apiKey;
   async function request(method, path, body, timeoutMs) {
     const headers = {
-      Authorization: `Bearer ${config2.apiKey}`
+      Authorization: `Bearer ${getApiKey()}`
     };
     if (body !== void 0) {
       headers["Content-Type"] = "application/json";
@@ -26991,6 +27049,24 @@ function createHttpClient(config2) {
         return { success: false, error: { code: "TRANSITION_FAILED", message } };
       }
     },
+    createPrForRevision: async (revisionId) => {
+      try {
+        const result = await request(
+          "POST",
+          `/api/revisions/${encodeURIComponent(revisionId)}/pr`
+        );
+        if (result === void 0) {
+          return { success: false, error: { code: "REVISION_NOT_FOUND", message: "Revision not found" } };
+        }
+        return { success: true, result };
+      } catch (err) {
+        if (err instanceof ApiError) {
+          const parsed = safeParseErrorBody(err.body);
+          return { success: false, error: { code: parsed?.code ?? "PR_CREATE_FAILED", message: parsed?.error ?? err.message } };
+        }
+        return { success: false, error: { code: "PR_CREATE_FAILED", message: err instanceof Error ? err.message : String(err) } };
+      }
+    },
     reconcileRevisionToState: async (revisionId, targetState, options) => {
       const forwardPath = ["planning", "building", "ready_for_drop", "in_staging", "ready_for_production", "live"];
       const revision = await request("GET", `/api/revisions/${encodeURIComponent(revisionId)}`);
@@ -27097,7 +27173,7 @@ function createHttpClient(config2) {
         res = await fetch(url2, {
           method: "GET",
           headers: {
-            Authorization: `Bearer ${config2.apiKey}`,
+            Authorization: `Bearer ${getApiKey()}`,
             Accept: "text/event-stream"
           },
           signal: controller.signal
@@ -27340,14 +27416,14 @@ function createHttpClient(config2) {
       return pollTaskResult(enqueued.taskId);
     },
     // Agent sessions
-    implementRevision: async (revisionId, projectId, triggeredBy) => {
+    startSession: async (projectId, message, triggeredBy) => {
       const result = await request(
         "POST",
-        `/api/projects/${encodeURIComponent(projectId)}/revisions/${encodeURIComponent(revisionId)}/implement`,
-        triggeredBy ? { triggeredBy } : {}
+        `/api/sessions`,
+        { projectId, message, ...triggeredBy && { triggeredBy } }
       );
-      if (!result?.taskId) throw new Error("Revision implementation enqueue failed: no taskId returned");
-      return { taskId: result.taskId, taskType: "revision_implementation", status: result.status ?? "pending", projectId, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
+      if (!result?.taskId) throw new Error("Start session enqueue failed: no taskId returned");
+      return { taskId: result.taskId, taskType: "generic_session", status: result.status ?? "pending", projectId, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
     },
     planRevisionBatch: async (projectId, revisionIds) => {
       const result = await request(
@@ -27783,7 +27859,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"0.31.0"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"1.0.0"} starting\u2026`);
   const config2 = loadConfig();
   const client = createHttpClient({
     apiBaseUrl: config2.apiBaseUrl,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codazen/harmonica-mcp",
-  "version": "0.31.0",
-  "description": "MCP server for Harmonica — connect Claude to your Harmonica projects",
+  "version": "1.0.0",
+  "description": "MCP server for Harmonica — connect any MCP-compatible AI assistant to Harmonica",
   "license": "MIT",
   "bin": {
     "harmonica-mcp": "./dist/index.js"