@gethmy/mcp 2.11.2 → 2.12.0

package/dist/cli.js

@@ -1858,6 +1858,14 @@ class HarmonyApiClient {
   async getCardExternalLinks(cardId) {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
+  async uploadArtifact(data) {
+    return this.request("POST", "/artifacts", data);
+  }
+  async createArtifactShareLink(artifactId, expiresAt) {
+    return this.request("POST", `/artifacts/${artifactId}/share`, {
+      expires_at: expiresAt
+    });
+  }
   async classifyCard(cardId) {
     return this.request("POST", `/cards/${cardId}/classify`);
   }
@@ -2324,6 +2332,24 @@ ${planContent.trim()}`;
       title: cardData.title
     };
   }
+  async listPlaybooks(workspaceId) {
+    return this.request("GET", `/playbooks?workspaceId=${encodeURIComponent(workspaceId)}`);
+  }
+  async getPlaybook(playbookId) {
+    return this.request("GET", `/playbooks/${playbookId}`);
+  }
+  async createPlaybook(data) {
+    return this.request("POST", "/playbooks", data);
+  }
+  async updatePlaybook(playbookId, updates) {
+    return this.request("PATCH", `/playbooks/${playbookId}`, updates);
+  }
+  async runPlaybook(playbookId) {
+    return this.request("POST", `/playbooks/${playbookId}/run`);
+  }
+  async savePlaybookFromCard(data) {
+    return this.request("POST", "/playbooks/from-card", data);
+  }
 }
 var _promptModules = null;
 async function loadPromptModules() {
@@ -3905,6 +3931,47 @@ var TOOLS = {
       required: ["cardId"]
     }
   },
+  harmony_upload_artifact: {
+    description: "Host a self-contained HTML document (e.g. a visual design draft or diagram) in Harmony and link it to a card, a plan, or a workspace. The file is stored privately and rendered in-app inside a sandboxed cross-origin iframe. Provide exactly one of cardId, planId, or workspaceId. Supply the HTML as `filePath` (a local path the MCP server can read) or `base64Data`. Only text/html, max 2MB. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description: "Display title (defaults to the file basename)."
+        },
+        cardId: { type: "string", description: "Link to this card (UUID)." },
+        planId: { type: "string", description: "Link to this plan (UUID)." },
+        workspaceId: {
+          type: "string",
+          description: "Attach to this workspace as a standalone artifact (UUID)."
+        },
+        filePath: {
+          type: "string",
+          description: "Absolute path to a local .html file the MCP server process can read. Mutually exclusive with base64Data."
+        },
+        base64Data: {
+          type: "string",
+          description: "Base64-encoded HTML bytes (a `data:` URL prefix is accepted and stripped). Mutually exclusive with filePath."
+        }
+      },
+      required: []
+    }
+  },
+  harmony_share_artifact: {
+    description: "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifactId: { type: "string", description: "Artifact UUID" },
+        expiresInDays: {
+          type: "number",
+          description: "Optional expiry in days. Omit for a link that never expires."
+        }
+      },
+      required: ["artifactId"]
+    }
+  },
   harmony_get_card_external_links: {
     description: "Get external URL references attached to a card (links to docs, gists, dashboards, etc.).",
     inputSchema: {
@@ -4864,6 +4931,110 @@ var TOOLS = {
       required: ["planId"]
     }
   },
+  harmony_list_playbook: {
+    description: "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, steps_version, and state. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description: "Workspace ID (optional if context set)"
+        }
+      },
+      required: []
+    }
+  },
+  harmony_get_playbook: {
+    description: "Get one playbook by ID, including its steps/stages definition and its recent runs. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: { type: "string", description: "Playbook ID (UUID)" }
+      },
+      required: ["playbookId"]
+    }
+  },
+  harmony_run_playbook: {
+    description: "Run a playbook server-side and return the finalized run. Only legacy automation playbooks (steps_version 1) are runnable; stage playbooks (steps_version 2) are rejected. The server drives every step to completion.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to run (UUID)"
+        }
+      },
+      required: ["playbookId"]
+    }
+  },
+  harmony_create_playbook: {
+    description: "Create a new playbook in a workspace. Default steps_version 1 is a legacy automation macro (an array of tool steps); steps_version 2 is the Method stage model (an array of stage objects).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description: "Workspace ID (optional if context set)"
+        },
+        name: { type: "string", description: "Playbook name" },
+        description: { type: "string", description: "Playbook description" },
+        stepsVersion: {
+          type: "number",
+          enum: [1, 2],
+          description: "1 = automation macro (tool steps), 2 = Method stage model (stage objects). Default 1."
+        },
+        steps: {
+          type: "array",
+          description: "Steps (steps_version 1: tool-step objects) or stages (steps_version 2: stage objects).",
+          items: { type: "object" }
+        }
+      },
+      required: ["name"]
+    }
+  },
+  harmony_update_playbook: {
+    description: "Update a playbook's name, description, steps/stages, enabled flag, or lifecycle state ('active'|'deprecated').",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to update (UUID)"
+        },
+        name: { type: "string", description: "New name" },
+        description: { type: "string", description: "New description" },
+        steps: {
+          type: "array",
+          description: "New steps (v1) or stages (v2) array.",
+          items: { type: "object" }
+        },
+        enabled: {
+          type: "boolean",
+          description: "Enable/disable the playbook"
+        },
+        state: {
+          type: "string",
+          enum: ["active", "deprecated"],
+          description: "Lifecycle state"
+        }
+      },
+      required: ["playbookId"]
+    }
+  },
+  harmony_save_card_as_playbook: {
+    description: "Save an existing card as a new steps_version 1 (automation) playbook, seeding one create-card step from the card. Returns the created playbook.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card ID to template (UUID)" },
+        name: {
+          type: "string",
+          description: "Name for the new playbook (defaults to the card title)"
+        }
+      },
+      required: ["cardId"]
+    }
+  },
   harmony_signup: {
     description: "Create a new user account. Returns a JWT session for subsequent authenticated calls. No API key required.",
     inputSchema: {
@@ -5412,6 +5583,50 @@ async function handleToolCall(name, args, deps) {
       });
       return result;
     }
+    case "harmony_upload_artifact": {
+      const title = args.title != null ? z.string().parse(args.title) : undefined;
+      const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
+      const planId = args.planId != null ? z.string().uuid().parse(args.planId) : undefined;
+      const workspaceId = args.workspaceId != null ? z.string().uuid().parse(args.workspaceId) : undefined;
+      const anchors = [cardId, planId, workspaceId].filter(Boolean);
+      if (anchors.length !== 1) {
+        throw new Error("Provide exactly one of cardId, planId, or workspaceId.");
+      }
+      const filePath = args.filePath != null ? z.string().parse(args.filePath) : undefined;
+      const base64Data = args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
+      if (filePath && base64Data) {
+        throw new Error("Provide either filePath or base64Data, not both.");
+      }
+      let data;
+      let inferredTitle = title;
+      if (filePath) {
+        const bytes = await readFile(filePath);
+        if (bytes.byteLength === 0) {
+          throw new Error(`File is empty: ${filePath}`);
+        }
+        data = bytes.toString("base64");
+        inferredTitle = inferredTitle || basename(filePath);
+      } else if (base64Data) {
+        data = base64Data;
+      } else {
+        throw new Error("Provide either filePath or base64Data.");
+      }
+      const result = await client3.uploadArtifact({
+        title: inferredTitle,
+        cardId,
+        planId,
+        workspaceId,
+        data
+      });
+      return result;
+    }
+    case "harmony_share_artifact": {
+      const artifactId = z.string().uuid().parse(args.artifactId);
+      const expiresInDays = args.expiresInDays != null ? z.number().positive().parse(args.expiresInDays) : undefined;
+      const expiresAt = expiresInDays ? new Date(Date.now() + expiresInDays * 86400000).toISOString() : undefined;
+      const result = await client3.createArtifactShareLink(artifactId, expiresAt);
+      return result;
+    }
     case "harmony_get_card_external_links": {
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client3.getCardExternalLinks(cardId);
@@ -6315,6 +6530,57 @@ async function handleToolCall(name, args, deps) {
         ...results
       };
     }
+    case "harmony_list_playbook": {
+      const workspaceId = args.workspaceId || getWorkspaceId();
+      const result = await client3.listPlaybooks(workspaceId);
+      return {
+        success: true,
+        playbooks: result.playbooks,
+        count: result.playbooks.length
+      };
+    }
+    case "harmony_get_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client3.getPlaybook(playbookId);
+      return { success: true, playbook: result.playbook, runs: result.runs };
+    }
+    case "harmony_run_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client3.runPlaybook(playbookId);
+      return { success: true, run: result.run };
+    }
+    case "harmony_create_playbook": {
+      const workspaceId = args.workspaceId || getWorkspaceId();
+      const name2 = z.string().min(1).max(200).parse(args.name);
+      const stepsVersion = args.stepsVersion !== undefined ? z.union([z.literal(1), z.literal(2)]).parse(args.stepsVersion) : undefined;
+      const result = await client3.createPlaybook({
+        workspaceId,
+        name: name2,
+        description: args.description,
+        steps: args.steps,
+        stepsVersion
+      });
+      return { success: true, playbook: result.playbook };
+    }
+    case "harmony_update_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client3.updatePlaybook(playbookId, {
+        name: args.name,
+        description: args.description,
+        steps: args.steps,
+        enabled: args.enabled,
+        state: args.state
+      });
+      return { success: true, playbook: result.playbook };
+    }
+    case "harmony_save_card_as_playbook": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const result = await client3.savePlaybookFromCard({
+        cardId,
+        name: args.name
+      });
+      return { success: true, playbook: result.playbook };
+    }
     case "harmony_signup": {
       const email = z.string().email().max(254).parse(args.email);
       const password = z.string().min(8).max(128).parse(args.password);

package/dist/index.js

@@ -1853,6 +1853,14 @@ class HarmonyApiClient {
   async getCardExternalLinks(cardId) {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
+  async uploadArtifact(data) {
+    return this.request("POST", "/artifacts", data);
+  }
+  async createArtifactShareLink(artifactId, expiresAt) {
+    return this.request("POST", `/artifacts/${artifactId}/share`, {
+      expires_at: expiresAt
+    });
+  }
   async classifyCard(cardId) {
     return this.request("POST", `/cards/${cardId}/classify`);
   }
@@ -2319,6 +2327,24 @@ ${planContent.trim()}`;
       title: cardData.title
     };
   }
+  async listPlaybooks(workspaceId) {
+    return this.request("GET", `/playbooks?workspaceId=${encodeURIComponent(workspaceId)}`);
+  }
+  async getPlaybook(playbookId) {
+    return this.request("GET", `/playbooks/${playbookId}`);
+  }
+  async createPlaybook(data) {
+    return this.request("POST", "/playbooks", data);
+  }
+  async updatePlaybook(playbookId, updates) {
+    return this.request("PATCH", `/playbooks/${playbookId}`, updates);
+  }
+  async runPlaybook(playbookId) {
+    return this.request("POST", `/playbooks/${playbookId}/run`);
+  }
+  async savePlaybookFromCard(data) {
+    return this.request("POST", "/playbooks/from-card", data);
+  }
 }
 var _promptModules = null;
 async function loadPromptModules() {
@@ -3900,6 +3926,47 @@ var TOOLS = {
       required: ["cardId"]
     }
   },
+  harmony_upload_artifact: {
+    description: "Host a self-contained HTML document (e.g. a visual design draft or diagram) in Harmony and link it to a card, a plan, or a workspace. The file is stored privately and rendered in-app inside a sandboxed cross-origin iframe. Provide exactly one of cardId, planId, or workspaceId. Supply the HTML as `filePath` (a local path the MCP server can read) or `base64Data`. Only text/html, max 2MB. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description: "Display title (defaults to the file basename)."
+        },
+        cardId: { type: "string", description: "Link to this card (UUID)." },
+        planId: { type: "string", description: "Link to this plan (UUID)." },
+        workspaceId: {
+          type: "string",
+          description: "Attach to this workspace as a standalone artifact (UUID)."
+        },
+        filePath: {
+          type: "string",
+          description: "Absolute path to a local .html file the MCP server process can read. Mutually exclusive with base64Data."
+        },
+        base64Data: {
+          type: "string",
+          description: "Base64-encoded HTML bytes (a `data:` URL prefix is accepted and stripped). Mutually exclusive with filePath."
+        }
+      },
+      required: []
+    }
+  },
+  harmony_share_artifact: {
+    description: "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifactId: { type: "string", description: "Artifact UUID" },
+        expiresInDays: {
+          type: "number",
+          description: "Optional expiry in days. Omit for a link that never expires."
+        }
+      },
+      required: ["artifactId"]
+    }
+  },
   harmony_get_card_external_links: {
     description: "Get external URL references attached to a card (links to docs, gists, dashboards, etc.).",
     inputSchema: {
@@ -4859,6 +4926,110 @@ var TOOLS = {
       required: ["planId"]
     }
   },
+  harmony_list_playbook: {
+    description: "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, steps_version, and state. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description: "Workspace ID (optional if context set)"
+        }
+      },
+      required: []
+    }
+  },
+  harmony_get_playbook: {
+    description: "Get one playbook by ID, including its steps/stages definition and its recent runs. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: { type: "string", description: "Playbook ID (UUID)" }
+      },
+      required: ["playbookId"]
+    }
+  },
+  harmony_run_playbook: {
+    description: "Run a playbook server-side and return the finalized run. Only legacy automation playbooks (steps_version 1) are runnable; stage playbooks (steps_version 2) are rejected. The server drives every step to completion.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to run (UUID)"
+        }
+      },
+      required: ["playbookId"]
+    }
+  },
+  harmony_create_playbook: {
+    description: "Create a new playbook in a workspace. Default steps_version 1 is a legacy automation macro (an array of tool steps); steps_version 2 is the Method stage model (an array of stage objects).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description: "Workspace ID (optional if context set)"
+        },
+        name: { type: "string", description: "Playbook name" },
+        description: { type: "string", description: "Playbook description" },
+        stepsVersion: {
+          type: "number",
+          enum: [1, 2],
+          description: "1 = automation macro (tool steps), 2 = Method stage model (stage objects). Default 1."
+        },
+        steps: {
+          type: "array",
+          description: "Steps (steps_version 1: tool-step objects) or stages (steps_version 2: stage objects).",
+          items: { type: "object" }
+        }
+      },
+      required: ["name"]
+    }
+  },
+  harmony_update_playbook: {
+    description: "Update a playbook's name, description, steps/stages, enabled flag, or lifecycle state ('active'|'deprecated').",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to update (UUID)"
+        },
+        name: { type: "string", description: "New name" },
+        description: { type: "string", description: "New description" },
+        steps: {
+          type: "array",
+          description: "New steps (v1) or stages (v2) array.",
+          items: { type: "object" }
+        },
+        enabled: {
+          type: "boolean",
+          description: "Enable/disable the playbook"
+        },
+        state: {
+          type: "string",
+          enum: ["active", "deprecated"],
+          description: "Lifecycle state"
+        }
+      },
+      required: ["playbookId"]
+    }
+  },
+  harmony_save_card_as_playbook: {
+    description: "Save an existing card as a new steps_version 1 (automation) playbook, seeding one create-card step from the card. Returns the created playbook.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card ID to template (UUID)" },
+        name: {
+          type: "string",
+          description: "Name for the new playbook (defaults to the card title)"
+        }
+      },
+      required: ["cardId"]
+    }
+  },
   harmony_signup: {
     description: "Create a new user account. Returns a JWT session for subsequent authenticated calls. No API key required.",
     inputSchema: {
@@ -5407,6 +5578,50 @@ async function handleToolCall(name, args, deps) {
       });
       return result;
     }
+    case "harmony_upload_artifact": {
+      const title = args.title != null ? z.string().parse(args.title) : undefined;
+      const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
+      const planId = args.planId != null ? z.string().uuid().parse(args.planId) : undefined;
+      const workspaceId = args.workspaceId != null ? z.string().uuid().parse(args.workspaceId) : undefined;
+      const anchors = [cardId, planId, workspaceId].filter(Boolean);
+      if (anchors.length !== 1) {
+        throw new Error("Provide exactly one of cardId, planId, or workspaceId.");
+      }
+      const filePath = args.filePath != null ? z.string().parse(args.filePath) : undefined;
+      const base64Data = args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
+      if (filePath && base64Data) {
+        throw new Error("Provide either filePath or base64Data, not both.");
+      }
+      let data;
+      let inferredTitle = title;
+      if (filePath) {
+        const bytes = await readFile(filePath);
+        if (bytes.byteLength === 0) {
+          throw new Error(`File is empty: ${filePath}`);
+        }
+        data = bytes.toString("base64");
+        inferredTitle = inferredTitle || basename(filePath);
+      } else if (base64Data) {
+        data = base64Data;
+      } else {
+        throw new Error("Provide either filePath or base64Data.");
+      }
+      const result = await client3.uploadArtifact({
+        title: inferredTitle,
+        cardId,
+        planId,
+        workspaceId,
+        data
+      });
+      return result;
+    }
+    case "harmony_share_artifact": {
+      const artifactId = z.string().uuid().parse(args.artifactId);
+      const expiresInDays = args.expiresInDays != null ? z.number().positive().parse(args.expiresInDays) : undefined;
+      const expiresAt = expiresInDays ? new Date(Date.now() + expiresInDays * 86400000).toISOString() : undefined;
+      const result = await client3.createArtifactShareLink(artifactId, expiresAt);
+      return result;
+    }
     case "harmony_get_card_external_links": {
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client3.getCardExternalLinks(cardId);
@@ -6310,6 +6525,57 @@ async function handleToolCall(name, args, deps) {
         ...results
       };
     }
+    case "harmony_list_playbook": {
+      const workspaceId = args.workspaceId || getWorkspaceId();
+      const result = await client3.listPlaybooks(workspaceId);
+      return {
+        success: true,
+        playbooks: result.playbooks,
+        count: result.playbooks.length
+      };
+    }
+    case "harmony_get_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client3.getPlaybook(playbookId);
+      return { success: true, playbook: result.playbook, runs: result.runs };
+    }
+    case "harmony_run_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client3.runPlaybook(playbookId);
+      return { success: true, run: result.run };
+    }
+    case "harmony_create_playbook": {
+      const workspaceId = args.workspaceId || getWorkspaceId();
+      const name2 = z.string().min(1).max(200).parse(args.name);
+      const stepsVersion = args.stepsVersion !== undefined ? z.union([z.literal(1), z.literal(2)]).parse(args.stepsVersion) : undefined;
+      const result = await client3.createPlaybook({
+        workspaceId,
+        name: name2,
+        description: args.description,
+        steps: args.steps,
+        stepsVersion
+      });
+      return { success: true, playbook: result.playbook };
+    }
+    case "harmony_update_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client3.updatePlaybook(playbookId, {
+        name: args.name,
+        description: args.description,
+        steps: args.steps,
+        enabled: args.enabled,
+        state: args.state
+      });
+      return { success: true, playbook: result.playbook };
+    }
+    case "harmony_save_card_as_playbook": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const result = await client3.savePlaybookFromCard({
+        cardId,
+        name: args.name
+      });
+      return { success: true, playbook: result.playbook };
+    }
     case "harmony_signup": {
       const email = z.string().email().max(254).parse(args.email);
       const password = z.string().min(8).max(128).parse(args.password);

package/dist/lib/api-client.js

@@ -1306,6 +1306,14 @@ class HarmonyApiClient {
   async getCardExternalLinks(cardId) {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
+  async uploadArtifact(data) {
+    return this.request("POST", "/artifacts", data);
+  }
+  async createArtifactShareLink(artifactId, expiresAt) {
+    return this.request("POST", `/artifacts/${artifactId}/share`, {
+      expires_at: expiresAt
+    });
+  }
   async classifyCard(cardId) {
     return this.request("POST", `/cards/${cardId}/classify`);
   }
@@ -1772,6 +1780,24 @@ ${planContent.trim()}`;
       title: cardData.title
     };
   }
+  async listPlaybooks(workspaceId) {
+    return this.request("GET", `/playbooks?workspaceId=${encodeURIComponent(workspaceId)}`);
+  }
+  async getPlaybook(playbookId) {
+    return this.request("GET", `/playbooks/${playbookId}`);
+  }
+  async createPlaybook(data) {
+    return this.request("POST", "/playbooks", data);
+  }
+  async updatePlaybook(playbookId, updates) {
+    return this.request("PATCH", `/playbooks/${playbookId}`, updates);
+  }
+  async runPlaybook(playbookId) {
+    return this.request("POST", `/playbooks/${playbookId}/run`);
+  }
+  async savePlaybookFromCard(data) {
+    return this.request("POST", "/playbooks/from-card", data);
+  }
 }
 var _promptModules = null;
 async function loadPromptModules() {

package/package.json

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

package/src/api-client.ts

@@ -681,6 +681,28 @@ export class HarmonyApiClient {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
 
+  // ============ ARTIFACTS (hosted HTML documents) ============
+
+  async uploadArtifact(data: {
+    title?: string;
+    cardId?: string;
+    planId?: string;
+    workspaceId?: string;
+    contentType?: string;
+    data: string;
+  }): Promise<{ artifact: Record<string, unknown> }> {
+    return this.request("POST", "/artifacts", data);
+  }
+
+  async createArtifactShareLink(
+    artifactId: string,
+    expiresAt?: string,
+  ): Promise<{ link: Record<string, unknown> }> {
+    return this.request("POST", `/artifacts/${artifactId}/share`, {
+      expires_at: expiresAt,
+    });
+  }
+
   async classifyCard(
     cardId: string,
   ): Promise<{ classification: CardClassificationResult }> {
@@ -1709,6 +1731,56 @@ export class HarmonyApiClient {
       title: cardData.title,
     };
   }
+
+  // ============ PLAYBOOKS (Method/Loop layer) ============
+
+  async listPlaybooks(workspaceId: string): Promise<{ playbooks: unknown[] }> {
+    return this.request(
+      "GET",
+      `/playbooks?workspaceId=${encodeURIComponent(workspaceId)}`,
+    );
+  }
+
+  async getPlaybook(
+    playbookId: string,
+  ): Promise<{ playbook: unknown; runs: unknown[] }> {
+    return this.request("GET", `/playbooks/${playbookId}`);
+  }
+
+  async createPlaybook(data: {
+    workspaceId: string;
+    name: string;
+    description?: string;
+    steps?: unknown;
+    stepsVersion?: number;
+    triggerType?: string;
+  }): Promise<{ playbook: unknown }> {
+    return this.request("POST", "/playbooks", data);
+  }
+
+  async updatePlaybook(
+    playbookId: string,
+    updates: {
+      name?: string;
+      description?: string;
+      steps?: unknown;
+      enabled?: boolean;
+      state?: string;
+    },
+  ): Promise<{ playbook: unknown }> {
+    return this.request("PATCH", `/playbooks/${playbookId}`, updates);
+  }
+
+  async runPlaybook(playbookId: string): Promise<{ run: unknown }> {
+    return this.request("POST", `/playbooks/${playbookId}/run`);
+  }
+
+  async savePlaybookFromCard(data: {
+    cardId: string;
+    name?: string;
+  }): Promise<{ playbook: unknown }> {
+    return this.request("POST", "/playbooks/from-card", data);
+  }
 }
 
 // Shared types for generateCardPrompt to avoid inline assertions

package/src/server.ts

@@ -705,6 +705,53 @@ export const TOOLS = {
       required: ["cardId"],
     },
   },
+  harmony_upload_artifact: {
+    description:
+      "Host a self-contained HTML document (e.g. a visual design draft or diagram) in Harmony and link it to a card, a plan, or a workspace. The file is stored privately and rendered in-app inside a sandboxed cross-origin iframe. Provide exactly one of cardId, planId, or workspaceId. Supply the HTML as `filePath` (a local path the MCP server can read) or `base64Data`. Only text/html, max 2MB. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description: "Display title (defaults to the file basename).",
+        },
+        cardId: { type: "string", description: "Link to this card (UUID)." },
+        planId: { type: "string", description: "Link to this plan (UUID)." },
+        workspaceId: {
+          type: "string",
+          description:
+            "Attach to this workspace as a standalone artifact (UUID).",
+        },
+        filePath: {
+          type: "string",
+          description:
+            "Absolute path to a local .html file the MCP server process can read. Mutually exclusive with base64Data.",
+        },
+        base64Data: {
+          type: "string",
+          description:
+            "Base64-encoded HTML bytes (a `data:` URL prefix is accepted and stripped). Mutually exclusive with filePath.",
+        },
+      },
+      required: [],
+    },
+  },
+  harmony_share_artifact: {
+    description:
+      "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifactId: { type: "string", description: "Artifact UUID" },
+        expiresInDays: {
+          type: "number",
+          description:
+            "Optional expiry in days. Omit for a link that never expires.",
+        },
+      },
+      required: ["artifactId"],
+    },
+  },
   harmony_get_card_external_links: {
     description:
       "Get external URL references attached to a card (links to docs, gists, dashboards, etc.).",
@@ -1754,6 +1801,126 @@ export const TOOLS = {
     },
   },
 
+  // ============ PLAYBOOK TOOLS (Method/Loop layer) ============
+
+  harmony_list_playbook: {
+    description:
+      "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, steps_version, and state. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description: "Workspace ID (optional if context set)",
+        },
+      },
+      required: [],
+    },
+  },
+
+  harmony_get_playbook: {
+    description:
+      "Get one playbook by ID, including its steps/stages definition and its recent runs. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: { type: "string", description: "Playbook ID (UUID)" },
+      },
+      required: ["playbookId"],
+    },
+  },
+
+  harmony_run_playbook: {
+    description:
+      "Run a playbook server-side and return the finalized run. Only legacy automation playbooks (steps_version 1) are runnable; stage playbooks (steps_version 2) are rejected. The server drives every step to completion.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to run (UUID)",
+        },
+      },
+      required: ["playbookId"],
+    },
+  },
+
+  harmony_create_playbook: {
+    description:
+      "Create a new playbook in a workspace. Default steps_version 1 is a legacy automation macro (an array of tool steps); steps_version 2 is the Method stage model (an array of stage objects).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description: "Workspace ID (optional if context set)",
+        },
+        name: { type: "string", description: "Playbook name" },
+        description: { type: "string", description: "Playbook description" },
+        stepsVersion: {
+          type: "number",
+          enum: [1, 2],
+          description:
+            "1 = automation macro (tool steps), 2 = Method stage model (stage objects). Default 1.",
+        },
+        steps: {
+          type: "array",
+          description:
+            "Steps (steps_version 1: tool-step objects) or stages (steps_version 2: stage objects).",
+          items: { type: "object" },
+        },
+      },
+      required: ["name"],
+    },
+  },
+
+  harmony_update_playbook: {
+    description:
+      "Update a playbook's name, description, steps/stages, enabled flag, or lifecycle state ('active'|'deprecated').",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to update (UUID)",
+        },
+        name: { type: "string", description: "New name" },
+        description: { type: "string", description: "New description" },
+        steps: {
+          type: "array",
+          description: "New steps (v1) or stages (v2) array.",
+          items: { type: "object" },
+        },
+        enabled: {
+          type: "boolean",
+          description: "Enable/disable the playbook",
+        },
+        state: {
+          type: "string",
+          enum: ["active", "deprecated"],
+          description: "Lifecycle state",
+        },
+      },
+      required: ["playbookId"],
+    },
+  },
+
+  harmony_save_card_as_playbook: {
+    description:
+      "Save an existing card as a new steps_version 1 (automation) playbook, seeding one create-card step from the card. Returns the created playbook.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card ID to template (UUID)" },
+        name: {
+          type: "string",
+          description: "Name for the new playbook (defaults to the card title)",
+        },
+      },
+      required: ["cardId"],
+    },
+  },
+
   // ============ ONBOARDING TOOLS ============
   harmony_signup: {
     description:
@@ -2559,6 +2726,73 @@ async function handleToolCall(
       return result;
     }
 
+    case "harmony_upload_artifact": {
+      const title =
+        args.title != null ? z.string().parse(args.title) : undefined;
+      const cardId =
+        args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
+      const planId =
+        args.planId != null ? z.string().uuid().parse(args.planId) : undefined;
+      const workspaceId =
+        args.workspaceId != null
+          ? z.string().uuid().parse(args.workspaceId)
+          : undefined;
+      const anchors = [cardId, planId, workspaceId].filter(Boolean);
+      if (anchors.length !== 1) {
+        throw new Error(
+          "Provide exactly one of cardId, planId, or workspaceId.",
+        );
+      }
+
+      const filePath =
+        args.filePath != null ? z.string().parse(args.filePath) : undefined;
+      const base64Data =
+        args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
+      if (filePath && base64Data) {
+        throw new Error("Provide either filePath or base64Data, not both.");
+      }
+
+      let data: string;
+      let inferredTitle = title;
+      if (filePath) {
+        const bytes = await readFile(filePath);
+        if (bytes.byteLength === 0) {
+          throw new Error(`File is empty: ${filePath}`);
+        }
+        data = bytes.toString("base64");
+        inferredTitle = inferredTitle || basename(filePath);
+      } else if (base64Data) {
+        data = base64Data;
+      } else {
+        throw new Error("Provide either filePath or base64Data.");
+      }
+
+      const result = await client.uploadArtifact({
+        title: inferredTitle,
+        cardId,
+        planId,
+        workspaceId,
+        data,
+      });
+      return result;
+    }
+
+    case "harmony_share_artifact": {
+      const artifactId = z.string().uuid().parse(args.artifactId);
+      const expiresInDays =
+        args.expiresInDays != null
+          ? z.number().positive().parse(args.expiresInDays)
+          : undefined;
+      const expiresAt = expiresInDays
+        ? new Date(Date.now() + expiresInDays * 86_400_000).toISOString()
+        : undefined;
+      const result = await client.createArtifactShareLink(
+        artifactId,
+        expiresAt,
+      );
+      return result;
+    }
+
     case "harmony_get_card_external_links": {
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client.getCardExternalLinks(cardId);
@@ -4028,6 +4262,68 @@ async function handleToolCall(
       };
     }
 
+    // ============ PLAYBOOK TOOLS (Method/Loop layer) ============
+
+    case "harmony_list_playbook": {
+      const workspaceId = (args.workspaceId as string) || getWorkspaceId();
+      const result = await client.listPlaybooks(workspaceId);
+      return {
+        success: true,
+        playbooks: result.playbooks,
+        count: (result.playbooks as unknown[]).length,
+      };
+    }
+
+    case "harmony_get_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client.getPlaybook(playbookId);
+      return { success: true, playbook: result.playbook, runs: result.runs };
+    }
+
+    case "harmony_run_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client.runPlaybook(playbookId);
+      return { success: true, run: result.run };
+    }
+
+    case "harmony_create_playbook": {
+      const workspaceId = (args.workspaceId as string) || getWorkspaceId();
+      const name = z.string().min(1).max(200).parse(args.name);
+      const stepsVersion =
+        args.stepsVersion !== undefined
+          ? z.union([z.literal(1), z.literal(2)]).parse(args.stepsVersion)
+          : undefined;
+      const result = await client.createPlaybook({
+        workspaceId,
+        name,
+        description: args.description as string | undefined,
+        steps: args.steps,
+        stepsVersion,
+      });
+      return { success: true, playbook: result.playbook };
+    }
+
+    case "harmony_update_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client.updatePlaybook(playbookId, {
+        name: args.name as string | undefined,
+        description: args.description as string | undefined,
+        steps: args.steps,
+        enabled: args.enabled as boolean | undefined,
+        state: args.state as string | undefined,
+      });
+      return { success: true, playbook: result.playbook };
+    }
+
+    case "harmony_save_card_as_playbook": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const result = await client.savePlaybookFromCard({
+        cardId,
+        name: args.name as string | undefined,
+      });
+      return { success: true, playbook: result.playbook };
+    }
+
     // ============ ONBOARDING TOOLS ============
     case "harmony_signup": {
       const email = z.string().email().max(254).parse(args.email);